--- openapi: 3.1.0 info: title: Scan.com API version: v2 description: "This API provides comprehensive access to Scan.com’s core functionalities, \nincluding management of referrals, patient information, authentication, body parts, \nand imaging modalities. It enables seamless integration for scheduling, data retrieval, \nand workflow automation within the Scan.com platform, facilitating efficient and secure \nhandling of medical imaging processes.\n" 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. servers: - url: https://api.staging.scan.com description: Sandbox - url: https://api.scan.com description: Production security: - BearerAuth: [] components: 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. headers: RequestId: description: Correlate this response with Scan support. schema: type: string responses: 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 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 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 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 ForbiddenError: type: object properties: error: type: string example: This endpoint is not enabled for your account required: - error 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 AutoBookCompletedEvent: type: object required: - event_name - occurred_at - auto_book_request - referral properties: event_name: type: string enum: - referral.auto_book_completed occurred_at: type: string format: date-time auto_book_request: "$ref": "#/components/schemas/AutoBookRequest" referral: "$ref": "#/components/schemas/ReferralResource" PatientResource: type: object properties: id: type: string format: uuid first_name: type: string middle_initial: type: string nullable: true last_name: type: string email: type: string format: email nullable: true phone_number: type: string date_of_birth: type: string nullable: true description: MM/DD/YYYY. Deprecated. Prefer `date_of_birth_iso`. date_of_birth_iso: type: string format: date nullable: true identifier: type: object properties: system: type: string example: https://scan.com/fhir/sid/patient-id value: type: string format: uuid 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 gender: type: string nullable: true weight: type: integer nullable: true height_feet: type: integer nullable: true height_inches: type: integer nullable: true ReferralNotification: type: object description: Delivery metadata for an email or SMS associated with a referral required: - id - channel - notification_type - status - created_at - updated_at properties: id: type: string format: uuid channel: type: string enum: - email - sms notification_type: type: string nullable: true description: Stable template identifier for the communication example: hard_confirmation_to_patient status: type: string description: | Current delivery status. `pending` and `dispatched` are set by Scan; the rest come from the delivery provider, so the channels differ. Email reports `sent`, `delivered`, `opened`, `temporary_failure`, or `permanent_failure`. SMS reports `sent`, `delivered`, or `failed`. Ignore values you do not recognize. example: delivered created_at: type: string format: date-time updated_at: type: string format: date-time description: Last delivery-status update time visit_id: type: string format: uuid nullable: true description: Visit associated with the notification, when it is visit-specific ReferralPayment: type: object description: A payment logged against a referral required: - id - amount - date - procedures properties: id: type: string format: uuid amount: type: number format: double description: Amount received, in dollars example: 10.0 date: type: string format: date nullable: true description: Payment date. Null on older payments recorded without one example: "2026-09-01" check_number: type: string nullable: true example: "1002" procedures: type: array description: > Procedures this payment is allocated to. Empty when the payment is not allocated to a procedure. items: type: object required: - order_id - description properties: order_id: type: string format: uuid accession_id: type: string nullable: true description: Order `reference_id` cpt_code: type: string nullable: true description: type: string description: > Study description as shown in the portal, for example `MRI Left Ankle w/contrast` example: MRI Left Ankle w/contrast NotificationWebhookEvent: type: object description: Metadata-only notification status event sent to your webhook URL required: - event_id - event_name - referral_id - status - changes - notification - occurred_at properties: event_id: type: string format: uuid description: Stable event identifier reused for every delivery retry event_name: type: string enum: - notification.status_changed referral_id: type: string format: uuid status: type: string example: delivered changes: type: object required: - status properties: status: type: array minItems: 2 maxItems: 2 items: type: string nullable: true example: - sent - delivered notification: "$ref": "#/components/schemas/ReferralNotification" occurred_at: type: string format: date-time ReferralWebhookEvent: type: object description: JSON POST body sent to your webhook_url required: - event_id - event_name - status - changes - visit_id - occurred_at - referral properties: event_id: type: string format: uuid description: Stable event identifier reused for every delivery retry event_name: type: string enum: - visit.status_changed description: Webhook event identifier example: visit.status_changed status: type: string description: | Visit status after the change. Fires on every status change, not only post-scan ones. 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 changes: type: object description: Fields that changed on this event required: - status properties: status: type: array description: Previous and current visit status minItems: 2 maxItems: 2 items: type: string example: - pending - booked visit_id: type: string format: uuid description: Visit that changed example: 11111111-1111-1111-1111-111111111111 occurred_at: type: string format: date-time description: When the status change was committed (ISO 8601) example: "2026-05-28T18:00:00Z" referral: "$ref": "#/components/schemas/ReferralResource" webhooks: autoBookCompleted: post: operationId: autoBookCompleted tags: - Webhooks security: [] summary: Auto-book completed description: | Sent after an asynchronous auto-book attempt reaches a terminal result. Scan sends this first to the `webhook_url` supplied on the booking request, otherwise to the group's configured `api_credentials.webhook_url`. If neither exists, poll the referral. This event does not currently include `event_id`. Store the `auto_book_request.id` and terminal `status` to make processing idempotent. When the callback uses the group's configured webhook, Scan signs the raw body with that API credential's signing secret and includes `X-Scan-Timestamp` and `X-Scan-Signature` headers. **Request headers** | Header | Value | |--------|--------| | Content-Type | application/json | | User-Agent | Scan.com-Webhook/1.0 | | X-Scan-Event | referral.auto_book_completed | | X-Scan-Timestamp | Unix timestamp used in the signature (configured webhooks only) | | X-Scan-Signature | `v1=` followed by the HMAC-SHA256 digest (configured webhooks only) | requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AutoBookCompletedEvent" responses: "200": description: Return any 2xx response to acknowledge the event statusChanged: post: operationId: visitStatusChanged tags: - Webhooks security: [] summary: Status changed description: | Scan.com sends an HTTP POST to the `webhook_url` on your `api_credentials` record when a visit status changes. Your endpoint must accept JSON and return HTTP 2xx. **Request headers** | Header | Value | |--------|--------| | Content-Type | application/json | | User-Agent | Scan.com-Webhook/1.0 | | X-Scan-Event | visit.status_changed | | X-Scan-Timestamp | Unix timestamp used in the signature | | X-Scan-Signature | `v1=` followed by the HMAC-SHA256 digest | Verify the signature by computing HMAC-SHA256 with your signing secret over `"{timestamp}.{raw_body}"`, using the exact request bytes. requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ReferralWebhookEvent" examples: "Status changed": summary: Status changed value: event_id: 55555555-5555-5555-5555-555555555555 event_name: visit.status_changed status: booked changes: status: - pending - booked visit_id: 11111111-1111-1111-1111-111111111111 occurred_at: "2026-05-28T18:00:00Z" referral: id: 22222222-2222-2222-2222-222222222222 reference: "1234567890" status: pending visits: - id: 11111111-1111-1111-1111-111111111111 modality: MRI procedures: - body_part: Brain procedure: MRI Brain w/o 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: series_uid: image_link: report_link: status: booked start_time: "2026-05-28T14:00:00Z" radiologist_group_name: East Coast Radiology location: id: 11111111-1111-1111-1111-111111111111 name: Midtown Imaging Center address_line_1: 123 Main St address_line_2: Suite 200 city: Atlanta 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: 33333333-3333-3333-3333-333333333333 identifier: system: https://scan.com/fhir/sid/patient-id value: 33333333-3333-3333-3333-333333333333 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" call_notes: - created_at: "2026-05-27T10:30:00Z" notes: Patient confirmed appointment window. responses: "200": description: Your endpoint acknowledged the event notificationStatusChanged: post: operationId: notificationStatusChanged tags: - Webhooks security: [] summary: Notification status changed description: | Sent when an email or SMS notification is created or its delivery status changes. This event is metadata-only and never includes recipient details or message content. Configure an HTTPS webhook URL and ask Scan to enable notification webhooks for your account. Delivery is at least once; deduplicate using `event_id`. Your endpoint must return HTTP 2xx. **Request headers** | Header | Value | |--------|--------| | Content-Type | application/json | | User-Agent | Scan.com-Webhook/1.0 | | X-Scan-Event | notification.status_changed | | X-Scan-Timestamp | Unix timestamp used in the signature | | X-Scan-Signature | `v1=` followed by the HMAC-SHA256 digest | Verify the signature by computing HMAC-SHA256 with your signing secret over `"{timestamp}.{raw_body}"`, using the exact request bytes. requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/NotificationWebhookEvent" example: event_id: 66666666-6666-6666-6666-666666666666 event_name: notification.status_changed referral_id: 22222222-2222-2222-2222-222222222222 status: delivered changes: status: - sent - delivered notification: id: 44444444-4444-4444-4444-444444444444 channel: sms notification_type: hard_confirmation_to_patient status: delivered created_at: "2026-09-21T18:00:00Z" updated_at: "2026-09-21T18:00:08Z" visit_id: 11111111-1111-1111-1111-111111111111 occurred_at: "2026-09-21T18:00:08Z" responses: "200": description: Return any 2xx response to acknowledge the event paths: "/api/v2/auth/sso": post: operationId: createCourierSsoUrl x-mint: href: /api-reference/courier-sso/creates-a-courier-portal-sso-url summary: Creates a Courier portal SSO URL tags: - Courier SSO security: - BearerAuth: [] description: | Mints a one-time SSO token for the authenticated partner and returns a URL to open Courier (`/sso/`). Opening that URL establishes a portal session. Send the same `Authorization: Bearer ` used for the rest of the API. parameters: [] responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: SSO URL created content: application/json: examples: SSO URL created: value: url: https://portal.scan.com/sso/eyJhbGciOiJIUzI1NiJ9... schema: type: object properties: url: type: string format: uri description: Courier portal SSO URL including a one-time token required: - url "401": "$ref": "#/components/responses/Unauthorized" "422": "$ref": "#/components/responses/UnprocessableEntity" "/api/v2/body_parts": get: operationId: listBodyParts x-mint: href: /api-reference/body-parts/returns-a-list-of-body-parts summary: Returns a list of body parts tags: - Body Parts description: "Returns a list of body parts that can be scanned.\n\nDifferent modalities support different body parts. Call without parameters to retrieve all supported body parts, \nor include the modality parameter to filter results to body parts available for a specific scan type.\n" security: - BearerAuth: [] parameters: - name: modality in: query required: false description: Filter by modality (name or ID) schema: type: string responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: body parts list content: application/json: examples: body parts list: value: - id: 11111111-1111-1111-1111-111111111111 name: Head slug: head laterality: false - id: 11111111-1111-1111-1111-111111111112 name: Arm slug: arm laterality: true schema: type: array items: type: object properties: id: type: string format: uuid name: type: string slug: type: string laterality: type: boolean "401": "$ref": "#/components/responses/Unauthorized" "/api/v2/cpt_codes": get: operationId: listCptCodes x-mint: href: /api-reference/cpt-codes/returns-cpt-code-mappings summary: Returns CPT code mappings tags: - CPT Codes description: | Returns every procedure mapping for an exact CPT code. A code can have multiple mappings when modality, body part, contrast, laterality, modifier, or number of views differs. security: - BearerAuth: [] parameters: - name: code in: query required: true description: Exact CPT code schema: type: string example: "70551" responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: CPT code mappings content: application/json: examples: CPT code mappings: value: - id: 11111111-1111-1111-1111-111111111113 code: "70551" modality_id: 11111111-1111-1111-1111-111111111111 modality_name: MRI body_part_id: 11111111-1111-1111-1111-111111111112 body_part_name: Brain contrast: without_contrast laterality: not_present modifier_id: modifier_name: number_of_views: schema: type: array items: type: object properties: id: type: string format: uuid code: type: string modality_id: type: string format: uuid modality_name: type: string body_part_id: type: string format: uuid body_part_name: type: string contrast: type: string enum: - with_contrast - without_contrast - without_and_with_contrast laterality: type: string enum: - left - right - not_present modifier_id: type: string format: uuid nullable: true modifier_name: type: string nullable: true number_of_views: type: integer minimum: 1 maximum: 6 nullable: true required: - id - code - modality_id - modality_name - body_part_id - body_part_name - contrast - laterality "400": description: code parameter missing content: application/json: schema: type: object properties: error: type: string example: Code is required "401": "$ref": "#/components/responses/Unauthorized" "/api/v2/icd10_codes": get: operationId: listIcd10Codes x-mint: href: /api-reference/icd-10-codes/returns-a-list-of-icd-10-codes summary: Returns a list of ICD-10 codes tags: - ICD-10 Codes description: "Returns a paginated list of ICD-10 diagnosis codes. Use q to search by code or short description, \nand ids to include selected codes in the response.\n" security: - BearerAuth: [] parameters: - name: q in: query required: false description: Search term matched against ICD-10 code or short description schema: type: string - name: ids in: query required: false description: ICD-10 code IDs to include and prioritize in the response schema: type: array items: type: string format: uuid - name: page in: query required: false description: Page number schema: type: integer - name: per_page in: query required: false description: Number of ICD-10 codes per page schema: type: integer responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: ICD-10 codes list content: application/json: examples: ICD-10 codes list: value: icd10_codes: - id: 11111111-1111-1111-1111-111111111111 code: M54.50 short_description: Low back pain, unspecified - id: 11111111-1111-1111-1111-111111111112 code: S13.4XXA short_description: Sprain of ligaments of cervical spine, initial encounter meta: current_page: 1 next_page: prev_page: total_pages: 1 total_count: 2 schema: type: object properties: icd10_codes: type: array items: type: object properties: id: type: string format: uuid description: Unique ICD-10 code identifier code: type: string description: ICD-10 diagnosis code short_description: type: string description: Short ICD-10 diagnosis description required: - id - code - short_description 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 ICD-10 codes required: - icd10_codes - meta "401": "$ref": "#/components/responses/Unauthorized" "/api/v2/law_firms": post: operationId: createLawFirm x-mint: href: /api-reference/law-firms/creates-a-law-firm summary: Creates a law firm tags: - Law Firms description: "Creates a pending law firm request associated with the authenticated user. " security: - BearerAuth: [] parameters: [] responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "201": description: law firm created content: application/json: examples: law firm: value: law_firm: id: 11111111-1111-1111-1111-111111111111 name: Smith & Jones Law address_line_1: 123 Main St address_line_2: Suite 100 city: Atlanta state: GA zipcode: "30303" schema: type: object properties: law_firm: type: object properties: id: type: string format: uuid description: Unique law firm identifier name: type: string description: Law firm name address_line_1: type: string description: Primary address line address_line_2: type: string nullable: true description: Secondary address line city: type: string description: City state: type: string description: State abbreviation zipcode: type: string description: ZIP code required: - id - name - address_line_1 - city - state - zipcode required: - law_firm "401": "$ref": "#/components/responses/Unauthorized" "403": "$ref": "#/components/responses/Forbidden" "422": "$ref": "#/components/responses/UnprocessableEntity" requestBody: content: application/json: schema: type: object properties: law_firm: type: object properties: name: type: string description: Law firm name 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 zipcode: type: string description: ZIP code required: - name - city - state required: - law_firm required: true get: operationId: listLawFirms x-mint: href: /api-reference/law-firms/returns-a-list-of-law-firms summary: Returns a list of law firms tags: - Law Firms description: | Returns a paginated list of law firms matching the required search query. The query is matched against law firm name and associated user contact fields. security: - BearerAuth: [] parameters: - name: q in: query required: true description: Search term matched against law firm name and associated user contact fields schema: type: string - name: page in: query required: false description: Page number schema: type: integer - name: per_page in: query required: false description: Number of law firms per page schema: type: integer responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: law firms list content: application/json: examples: law firms list: value: law_firms: - id: 11111111-1111-1111-1111-111111111111 name: Smith & Jones Law address_line_1: 123 Main St address_line_2: Suite 100 city: Atlanta state: GA zipcode: "30303" - id: 11111111-1111-1111-1111-111111111112 name: Johnson Injury Law address_line_1: 456 Peachtree St address_line_2: city: Atlanta state: GA zipcode: "30308" meta: current_page: 1 next_page: prev_page: total_pages: 1 total_count: 2 schema: type: object properties: law_firms: type: array items: type: object properties: id: type: string format: uuid description: Unique law firm identifier name: type: string description: Law firm name address_line_1: type: string description: Primary address line address_line_2: type: string nullable: true description: Secondary address line city: type: string description: City state: type: string description: State abbreviation zipcode: type: string description: ZIP code required: - id - name - address_line_1 - city - state - zipcode 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 law firms required: - law_firms - meta "401": "$ref": "#/components/responses/Unauthorized" "403": "$ref": "#/components/responses/Forbidden" "422": "$ref": "#/components/responses/UnprocessableEntity" "/api/v2/modalities": get: operationId: listModalities x-mint: href: /api-reference/modalities/returns-a-list-of-modalities summary: Returns a list of modalities tags: - Modalities description: "Returns a list of modalities that are supported by the platform. " security: - BearerAuth: [] responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: modalities list content: application/json: examples: modalities list: value: - id: 11111111-1111-1111-1111-111111111111 name: MRI slug: mri-scan - id: 11111111-1111-1111-1111-111111111112 name: CT slug: ct-scan schema: type: array items: type: object properties: id: type: string format: uuid name: type: string slug: type: string "401": "$ref": "#/components/responses/Unauthorized" "/api/v2/patients": post: operationId: createPatient x-mint: href: /api-reference/patients/creates-a-patient summary: Creates a patient tags: - Patients description: | Creates a patient record for the authenticated user's group. security: - BearerAuth: [] parameters: [] responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "201": description: patient created content: application/json: examples: patient: value: patient: id: 11111111-1111-1111-1111-111111111111 first_name: John middle_initial: D last_name: Doe email: john.doe@example.com phone_number: "1234567890" date_of_birth: 05/21/1988 date_of_birth_iso: "1988-05-21" identifier: system: https://scan.com/fhir/sid/patient-id value: 11111111-1111-1111-1111-111111111111 address_line_1: 123 Main St address_line_2: "" city: New York state: NY zip_code: "10001" gender: male weight: 150 height_feet: 5 height_inches: 10 schema: type: object properties: patient: type: object properties: id: type: string format: uuid description: Patient unique identifier 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 (MM/DD/YYYY) 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 gender: type: string enum: - male - female - other description: Patient gender weight: type: integer description: Patient weight in pounds height_feet: type: integer description: Patient height in feet height_inches: type: integer description: Patient height in inches required: - id - first_name - last_name - phone_number - date_of_birth required: - patient "401": "$ref": "#/components/responses/Unauthorized" "422": "$ref": "#/components/responses/UnprocessableEntity" requestBody: content: application/json: schema: type: object properties: 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: type: string description: Patient phone number patient_profile_attributes: type: object properties: date_of_birth: type: string description: Patient date of birth (MM/DD/YYYY) 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 gender: type: string enum: - male - female - other description: Patient gender required: - date_of_birth required: - first_name - last_name - phone - patient_profile_attributes required: - patient required: true get: operationId: listPatients x-mint: href: /api-reference/patients/returns-a-list-of-patients summary: Returns a list of patients tags: - Patients description: "Returns a list of patients that are associated with the user group. " security: - BearerAuth: [] parameters: - name: page in: query required: false description: Page number schema: type: integer - name: per_page in: query required: false description: Number of patients per page schema: type: integer - name: billable in: query required: false description: When true, also include patients whose referral billing-company name matches the group schema: type: boolean responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: patients list content: application/json: examples: patients list: value: patients: - id: 11111111-1111-1111-1111-111111111111 first_name: John middle_initial: D last_name: Doe email: john.doe@example.com phone_number: "+1234567890" date_of_birth: 05/21/1988 date_of_birth_iso: "1988-05-21" identifier: system: https://scan.com/fhir/sid/patient-id value: 11111111-1111-1111-1111-111111111111 address_line_1: 123 Main St address_line_2: "" city: New York state: NY zip_code: "10001" gender: male weight: 150 height_feet: 5 height_inches: 10 meta: current_page: 1 next_page: 2 prev_page: total_pages: 1 total_count: 1 schema: type: object properties: patients: type: array items: type: object properties: id: type: string format: uuid description: Unique patient identifier 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 (YYYY-MM-DD) 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 gender: type: string enum: - male - female - other description: Patient gender weight: type: integer description: Patient weight in pounds height_feet: type: integer description: Height in feet height_inches: type: integer description: Additional height in inches 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 patients "401": "$ref": "#/components/responses/Unauthorized" "/api/v2/patients/{id}": get: operationId: getPatient x-mint: href: /api-reference/patients/returns-a-patient-by-id summary: Returns a patient by ID tags: - Patients description: "Returns a patient by ID. " security: - BearerAuth: [] parameters: - name: id in: path required: true description: Patient ID schema: type: string responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: patient content: application/json: examples: patient: value: id: 11111111-1111-1111-1111-111111111111 first_name: John middle_initial: D last_name: Doe email: john.doe@example.com phone_number: "+1234567890" date_of_birth: 05/21/1988 date_of_birth_iso: "1988-05-21" identifier: system: https://scan.com/fhir/sid/patient-id value: 11111111-1111-1111-1111-111111111111 address_line_1: 123 Main St address_line_2: "" city: New York state: NY zip_code: "10001" gender: male weight: 150 height_feet: 5 height_inches: 10 schema: type: object properties: id: type: string format: uuid description: Unique patient identifier 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 (MM/DD/YYYY) 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 gender: type: string enum: - male - female - other description: Patient gender weight: type: integer description: Patient weight in pounds height_feet: type: integer description: Height in feet height_inches: type: integer description: Additional height in inches "401": "$ref": "#/components/responses/Unauthorized" "404": "$ref": "#/components/responses/NotFound" patch: operationId: updatePatient x-mint: href: /api-reference/patients/updates-a-patient summary: Updates a patient tags: - Patients description: Updates a patient belonging to the authenticated group. security: - BearerAuth: [] parameters: - name: id in: path required: true description: Patient ID schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: - patient properties: patient: type: object properties: first_name: type: string middle_initial: type: string last_name: type: string email: type: string format: email phone: type: string patient_profile_attributes: type: object properties: date_of_birth: type: string format: date gender: type: string address_line_1: type: string address_line_2: type: string city: type: string state: type: string zip_code: type: string responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: patient updated content: application/json: schema: "$ref": "#/components/schemas/PatientResource" "401": "$ref": "#/components/responses/Unauthorized" "404": "$ref": "#/components/responses/NotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" "/api/v2/practices": post: operationId: createPractice x-mint: href: /api-reference/practices/creates-a-practice summary: Creates a practice tags: - Practices description: "Creates a pending referring practice request associated with the authenticated user. " security: - BearerAuth: [] parameters: [] responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "201": description: practice created content: application/json: examples: practice: value: practice: id: 11111111-1111-1111-1111-111111111111 name: Peachtree Orthopedics address_line_1: 123 Main St address_line_2: Suite 100 city: Atlanta state: GA zipcode: "30303" schema: type: object properties: practice: type: object properties: id: type: string format: uuid description: Unique practice identifier name: type: string description: Practice name address_line_1: type: string description: Primary address line address_line_2: type: string nullable: true description: Secondary address line city: type: string description: City state: type: string description: State abbreviation zipcode: type: string description: ZIP code required: - id - name - address_line_1 - city - state - zipcode required: - practice "401": "$ref": "#/components/responses/Unauthorized" "403": "$ref": "#/components/responses/Forbidden" "422": "$ref": "#/components/responses/UnprocessableEntity" requestBody: content: application/json: schema: type: object properties: practice: type: object properties: name: type: string description: Practice name 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 zipcode: type: string description: ZIP code required: - name - state required: - practice required: true get: operationId: listPractices x-mint: href: /api-reference/practices/returns-a-list-of-practices summary: Returns a list of practices tags: - Practices description: "Returns a paginated list of referring practices matching the required search query. " security: - BearerAuth: [] parameters: - name: q in: query required: true description: Search term matched against practice name schema: type: string - name: page in: query required: false description: Page number schema: type: integer - name: per_page in: query required: false description: Number of practices per page schema: type: integer responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: practices list content: application/json: examples: practices list: value: practices: - id: 11111111-1111-1111-1111-111111111111 name: Peachtree Orthopedics address_line_1: 123 Main St address_line_2: Suite 100 city: Atlanta state: GA zipcode: "30303" - id: 11111111-1111-1111-1111-111111111112 name: Midtown Spine Clinic address_line_1: 456 Peachtree St address_line_2: city: Atlanta state: GA zipcode: "30308" meta: current_page: 1 next_page: prev_page: total_pages: 1 total_count: 2 schema: type: object properties: practices: type: array items: type: object properties: id: type: string format: uuid description: Unique practice identifier name: type: string description: Practice name address_line_1: type: string description: Primary address line address_line_2: type: string nullable: true description: Secondary address line city: type: string description: City state: type: string description: State abbreviation zipcode: type: string description: ZIP code required: - id - name - address_line_1 - city - state - zipcode 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 practices required: - practices - meta "401": "$ref": "#/components/responses/Unauthorized" "403": "$ref": "#/components/responses/Forbidden" "422": "$ref": "#/components/responses/UnprocessableEntity" "/api/v2/practices/{practice_id}/users": parameters: - name: practice_id in: path required: true description: Practice ID schema: type: string get: operationId: listPracticeUsers x-mint: href: /api-reference/practices/returns-users-for-a-practice summary: Returns users for a practice tags: - Practices description: "Returns a paginated list of users belonging to the given practice, ordered by full name. " security: - BearerAuth: [] parameters: - name: page in: query required: false description: Page number schema: type: integer - name: per_page in: query required: false description: Number of users per page schema: type: integer responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: users list content: application/json: examples: users list: value: users: - id: 11111111-1111-1111-1111-111111111111 full_name: Ada Lovelace email: ada.lovelace@example.com phone_number: "4045550100" npi: "1234567890" meta: current_page: 1 next_page: prev_page: total_pages: 1 total_count: 1 schema: type: object properties: users: type: array items: type: object properties: id: type: string format: uuid description: Unique user identifier full_name: type: string description: User full name email: type: string format: email description: User email address phone_number: type: string description: User phone number npi: type: string description: National Provider Identifier required: - id - full_name - email 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 users required: - users - meta "401": "$ref": "#/components/responses/Unauthorized" "404": "$ref": "#/components/responses/NotFound" post: operationId: createPracticeUser x-mint: href: /api-reference/practices/creates-a-user-on-a-practice summary: Creates a user on a practice tags: - Practices description: | Creates a user associated with the given practice. When `role_attributes` is omitted, the role defaults to `provider`. security: - BearerAuth: [] parameters: [] responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "201": description: user created content: application/json: examples: user: value: user: id: 11111111-1111-1111-1111-111111111111 full_name: Grace Hopper email: grace.hopper@example.com phone_number: "4045550100" npi: "1234567890" schema: type: object properties: user: type: object properties: id: type: string format: uuid description: Unique user identifier full_name: type: string description: User full name email: type: string format: email description: User email address phone_number: type: string description: User phone number npi: type: string description: National Provider Identifier required: - id - full_name - email required: - user "401": "$ref": "#/components/responses/Unauthorized" "404": "$ref": "#/components/responses/NotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" requestBody: content: application/json: schema: type: object properties: user: type: object properties: full_name: type: string description: User full name email: type: string format: email description: User email address phone_number: type: string description: User phone number npi: type: string description: National Provider Identifier role_attributes: type: object properties: role_type: type: string description: Role type (defaults to provider when omitted) enum: - provider required: - full_name - email required: - user required: true "/api/v2/referral_orders": post: operationId: createReferralOrder x-mint: href: /api-reference/referral-orders/submits-an-order-form-referral summary: Submits an order form referral tags: - Referral Orders 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. security: - BearerAuth: [] parameters: [] responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "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" 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 "/api/v2/referrals": post: operationId: createReferral x-mint: href: /api-reference/referrals/creates-a-referral summary: Creates a referral tags: - Referrals description: Creates an imaging referral for a patient, including visits and procedures. security: - BearerAuth: [] parameters: [] responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "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: series_uid: image_link: report_link: 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: 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" 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 get: operationId: listReferrals x-mint: href: /api-reference/referrals/returns-a-list-of-referrals summary: Returns a list of referrals tags: - Referrals description: "Returns a list of referrals that are associated with the user group. " security: - BearerAuth: [] 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: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "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: series_uid: image_link: report_link: 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: 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: 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" "/api/v2/referrals/{id}": get: operationId: getReferral x-mint: href: /api-reference/referrals/returns-a-referral-by-id summary: Returns a referral by ID tags: - Referrals description: "Returns a referral by ID. " security: - BearerAuth: [] parameters: - name: id in: path required: true description: Referral ID schema: type: string responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: referral 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: series_uid: image_link: https://example.com/images/11111111-1111-1111-1111-111111111111 report_link: https://example.com/report.pdf 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: city: Anytown state: GA zip_code: "30303" line_of_business: personal_injury payment_type: lien incident_state: GA 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" schema: $ref: "#/components/schemas/ReferralResource" "401": "$ref": "#/components/responses/Unauthorized" "404": "$ref": "#/components/responses/NotFound" patch: operationId: updateReferral x-mint: href: /api-reference/referrals/updates-a-referral summary: Updates a referral tags: - Referrals description: | Updates assignable ownership, ICD-10, and workers' compensation fields for a referral belonging to the authenticated group. security: - BearerAuth: [] 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: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "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" delete: operationId: cancelReferral x-mint: href: /api-reference/referrals/cancels-a-referral summary: Cancels a referral tags: - Referrals description: Cancels a referral belonging to the authenticated group. security: - BearerAuth: [] 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 required: - reason properties: reason: type: string description: Cancellation reason responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: referral canceled content: application/json: schema: type: object required: - message properties: message: type: string example: message: Referral canceled successfully "401": "$ref": "#/components/responses/Unauthorized" "404": "$ref": "#/components/responses/NotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" "/api/v2/referrals/{referral_id}/visits/{visit_id}/orders": parameters: - name: referral_id in: path required: true description: Referral ID schema: type: string - name: visit_id in: path required: true description: Visit ID schema: type: string post: operationId: createVisitOrder x-mint: href: /api-reference/referrals/creates-an-order-on-a-visit summary: Creates an order on a visit tags: - Referrals description: "Adds a procedure (order) to an existing visit on a referral. " security: - BearerAuth: [] parameters: [] responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "201": description: order created content: application/json: examples: order: value: order: id: 11111111-1111-1111-1111-111111111111 visit_id: 22222222-2222-2222-2222-222222222222 body_part_id: 33333333-3333-3333-3333-333333333333 contrast: without_contrast laterality: left schema: type: object properties: order: type: object properties: id: type: string format: uuid description: Unique order identifier visit_id: type: string format: uuid description: Visit ID 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 required: - id - visit_id - body_part_id - contrast - laterality required: - order "401": "$ref": "#/components/responses/Unauthorized" "404": "$ref": "#/components/responses/NotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" requestBody: content: application/json: schema: type: object properties: order: type: object properties: 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 required: - body_part_id - contrast - laterality required: - order required: true "/api/v2/referrals/{referral_id}/visits/{visit_id}/orders/{id}": parameters: - name: referral_id in: path required: true description: Referral ID schema: type: string - name: visit_id in: path required: true description: Visit ID schema: type: string - name: id in: path required: true description: Order ID schema: type: string patch: operationId: updateVisitOrder x-mint: href: /api-reference/referrals/updates-an-order-on-a-visit summary: Updates an order on a visit tags: - Referrals description: Updates procedure fields on an order. security: - BearerAuth: [] parameters: [] responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: order updated content: application/json: examples: order: value: order: id: 11111111-1111-1111-1111-111111111111 visit_id: 22222222-2222-2222-2222-222222222222 body_part_id: 33333333-3333-3333-3333-333333333333 contrast: with_contrast laterality: right schema: type: object properties: order: type: object properties: id: type: string format: uuid description: Unique order identifier visit_id: type: string format: uuid description: Visit ID 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 required: - id - visit_id - body_part_id - contrast - laterality required: - order "401": "$ref": "#/components/responses/Unauthorized" "404": "$ref": "#/components/responses/NotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" requestBody: content: application/json: schema: type: object properties: order: type: object properties: 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 required: - body_part_id - contrast - laterality required: - order required: true delete: operationId: deleteVisitOrder x-mint: href: /api-reference/referrals/deletes-an-order-on-a-visit summary: Deletes an order on a visit tags: - Referrals description: Soft-deletes an order from a visit. security: - BearerAuth: [] responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "204": description: order deleted "401": "$ref": "#/components/responses/Unauthorized" "404": "$ref": "#/components/responses/NotFound" "/api/v2/referrals/{referral_id}/notifications": get: operationId: listReferralNotifications x-mint: href: /api-reference/referrals/lists-referral-notification-delivery-history summary: Lists referral notification delivery history tags: - Referrals description: | Returns newest-first email and SMS delivery metadata attached to the referral or one of its visits. Recipient details, subjects, message bodies, email HTML, provider identifiers, and failure text are never returned. This capability is disabled until Scan enables notification read access for your account. security: - BearerAuth: [] parameters: - name: referral_id in: path required: true schema: type: string format: uuid - name: page in: query required: false schema: type: integer minimum: 1 default: 1 - name: per_page in: query required: false schema: type: integer minimum: 1 default: 20 responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: Referral notification delivery metadata content: application/json: schema: type: object required: - referral_notifications - meta properties: referral_notifications: type: array items: "$ref": "#/components/schemas/ReferralNotification" meta: type: object properties: current_page: type: integer next_page: type: integer nullable: true prev_page: type: integer nullable: true total_pages: type: integer total_count: type: integer "401": "$ref": "#/components/responses/Unauthorized" "403": "$ref": "#/components/responses/Forbidden" "404": "$ref": "#/components/responses/NotFound" "/api/v2/referrals/{referral_id}/payments": get: operationId: listReferralPayments x-mint: href: /api-reference/referrals/lists-referral-payments summary: Lists referral payments tags: - Referrals description: | Returns newest-first payments logged against the referral, including amount, payment date, check number, and any procedures the payment is allocated to. Procedure `description` matches the portal study string (for example `MRI Left Ankle w/contrast`). This capability is disabled until Scan enables payment read access for your account. security: - BearerAuth: [] parameters: - name: referral_id in: path required: true schema: type: string format: uuid - name: page in: query required: false schema: type: integer minimum: 1 default: 1 - name: per_page in: query required: false schema: type: integer minimum: 1 default: 20 responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: Referral payments content: application/json: schema: type: object required: - referral_payments - meta properties: referral_payments: type: array items: "$ref": "#/components/schemas/ReferralPayment" meta: type: object properties: current_page: type: integer next_page: type: integer nullable: true prev_page: type: integer nullable: true total_pages: type: integer total_count: type: integer "401": "$ref": "#/components/responses/Unauthorized" "403": "$ref": "#/components/responses/Forbidden" "404": "$ref": "#/components/responses/NotFound" "/api/v2/referrals/{referral_id}/medical_questionnaire": get: operationId: getMedicalQuestionnaire x-mint: href: /api-reference/referrals/returns-medical-safety-questions summary: Returns medical safety questions tags: - Referrals description: | Returns the medical safety questionnaire for a referral, including any answers already stored. Submit answers before listing nearby centers so ranking can apply open-scanner and weight filters. security: - BearerAuth: [] parameters: - name: referral_id in: path required: true description: Referral ID schema: type: string format: uuid responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: medical safety questions content: application/json: examples: questions: value: questions: - id: 11111111-1111-1111-1111-111111111111 key: claustrophobic label: Is the patient claustrophobic? question_type: boolean blocking: false follow_up: false answer: additional_detail: schema: type: object properties: questions: type: array items: type: object properties: id: type: string format: uuid key: type: string nullable: true label: type: string question_type: type: string blocking: type: boolean follow_up: type: boolean answer: type: string nullable: true additional_detail: type: string nullable: true sub_questions: type: array items: type: object "401": "$ref": "#/components/responses/Unauthorized" "404": "$ref": "#/components/responses/NotFound" put: operationId: updateMedicalQuestionnaire x-mint: href: /api-reference/referrals/submits-medical-safety-answers summary: Submits medical safety answers tags: - Referrals description: | Stores medical safety answers on the referral. Use the question `id` values from GET. Answers of yes on blocking questions (for example metal implants) can prevent live booking at some centers. security: - BearerAuth: [] parameters: - name: referral_id in: path required: true description: Referral ID schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: - medical_questionnaire properties: medical_questionnaire: type: array items: type: object required: - id - answer properties: id: type: string format: uuid description: Intake question ID answer: type: string description: Typically yes or no detail: type: string nullable: true description: Optional follow-up detail examples: answers: value: medical_questionnaire: - id: 11111111-1111-1111-1111-111111111111 answer: "no" detail: responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: answers stored content: application/json: schema: type: object properties: questions: type: array items: type: object "401": "$ref": "#/components/responses/Unauthorized" "404": "$ref": "#/components/responses/NotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" "/api/v2/referrals/{referral_id}/book": post: operationId: requestAutomaticBooking x-mint: href: /api-reference/referrals/requests-automatic-booking summary: Requests automatic booking tags: - Referrals description: | Asynchronously ranks eligible centers and books the best live opening. Partners do not select a timeslot. The response confirms that the request was accepted; it does not mean the visit is booked. This capability is off until Scan enables it for your account. This is the only endpoint that requires your API credential to have an acting user assigned, because the resulting booking is attributed to a person. Requests from a credential without one return `422`. security: - BearerAuth: [] parameters: - name: referral_id in: path required: true description: Existing referral ID schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: - book properties: book: type: object required: - strategy properties: strategy: type: string enum: - closest - soonest - closest_soonest radius: type: integer minimum: 1 maximum: 250 default: 200 description: Search radius in miles address: type: string description: Search origin. Defaults to the patient address without changing it. webhook_url: type: string format: uri pattern: "^https://" description: | Optional public HTTPS completion URL. If omitted, Scan uses the account webhook URL; if neither exists, poll GET referral. examples: closest within 25 miles: value: book: strategy: closest radius: 25 address: 200 Peachtree St, Atlanta, GA 30303 webhook_url: https://partner.example/hooks/scan-booking responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "202": description: auto-book request accepted content: application/json: schema: type: object required: - auto_book_request - referral properties: auto_book_request: "$ref": "#/components/schemas/AutoBookRequest" referral: "$ref": "#/components/schemas/ReferralResource" "401": "$ref": "#/components/responses/Unauthorized" "403": "$ref": "#/components/responses/Forbidden" "404": "$ref": "#/components/responses/NotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" "/api/v2/referrals/{referral_id}/scheduling_preferences": post: operationId: createSchedulingPreference x-mint: href: /api-reference/referrals/submits-preferred-center-and-availability summary: Submits preferred center and availability tags: - Referrals description: | Records how the patient prefers to be scheduled. Scan books the visit from this preference. `anytime_anywhere` needs no center. `time_preferences` requires a `location_id` from GET /api/v2/locations and either `preferred_times` or `asap: true`. security: - BearerAuth: [] parameters: - name: referral_id in: path required: true description: Referral ID schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: - scheduling_preference properties: scheduling_preference: type: object required: - mode properties: mode: type: string enum: - anytime_anywhere - time_preferences - existing_appointment - needs_other_location location_id: type: string format: uuid description: Preferred imaging center ID asap: type: boolean description: Book the soonest opening at the preferred center preferred_times: type: array items: type: object properties: day_of_week: type: string example: monday time_of_day: type: string example: morning center_name: type: string center_address: type: string start_time: type: string phone_number: type: string reason: type: string examples: time preferences: value: scheduling_preference: mode: time_preferences location_id: 11111111-1111-1111-1111-111111111111 preferred_times: - day_of_week: monday time_of_day: morning asap: false anytime: value: scheduling_preference: mode: anytime_anywhere responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: preference saved content: application/json: schema: $ref: "#/components/schemas/ReferralResource" "401": "$ref": "#/components/responses/Unauthorized" "404": "$ref": "#/components/responses/NotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" "/api/v2/locations": get: operationId: listReferralLocations x-mint: href: /api-reference/locations/returns-nearby-imaging-centers summary: Returns nearby imaging centers tags: - Locations description: | Ranks imaging centers near the patient for a referral. Call after medical safety answers are submitted. Does not return appointment timeslots; submit a preferred center with POST scheduling_preferences. security: - BearerAuth: [] parameters: - name: referral_id in: query required: true description: Referral ID schema: type: string format: uuid - name: address in: query required: false description: Search origin. Defaults to the patient's address. schema: type: string - name: radius in: query required: false description: Search radius in miles (default 60) schema: type: integer - name: visit_id in: query required: false description: Visit to rank for. Defaults to the first visit on the referral. schema: type: string format: uuid - name: limit in: query required: false description: Maximum centers to return (default 10) schema: type: integer responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: ranked imaging centers content: application/json: examples: locations: value: locations: - id: 11111111-1111-1111-1111-111111111111 name: Anytown Medical Center npi: "1234567890" address_line_1: 123 Main St address_line_2: city: Anytown state: GA zip_code: "30303" distance: 4.2 schema: type: object properties: locations: type: array items: type: object properties: id: type: string format: uuid name: type: string 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 distance: type: number nullable: true description: Distance in miles from the search origin "401": "$ref": "#/components/responses/Unauthorized" "403": "$ref": "#/components/responses/Forbidden" "404": "$ref": "#/components/responses/NotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" "/api/v2/order_documents": get: operationId: getOrderDocuments x-mint: href: /api-reference/order-documents/returns-report-and-dicom-for-an-order summary: Returns report and DICOM for an order tags: - Order Documents description: | Returns base64-encoded radiology report PDF and DICOM imaging data for a single order visible to the authenticated user's group. Provide **one** lookup method: - `order_id` — order UUID - `reference_id` — accession / reference ID on the order - `patient_name` + `date_of_birth` + `study_description` — patient and study description (study description is resolved via the Translation table, same as inbound image matching) `report` and `dicom` are omitted (null) when not available for the order. DICOM is returned as a base64-encoded zip when fetched live from Ambra storage. security: - BearerAuth: [] parameters: - name: order_id in: query required: false description: Order UUID (one lookup method required) schema: type: string - name: reference_id in: query required: false description: Order accession / reference ID (one lookup method required) schema: type: string - name: patient_name in: query required: false description: Patient full name — use with date_of_birth and study_description schema: type: string - name: date_of_birth in: query required: false description: Patient date of birth (YYYY-MM-DD) — use with patient_name and study_description schema: type: string - name: study_description in: query required: false description: Ambra study description matched via Translation table — use with patient_name and date_of_birth schema: type: string responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: order documents content: application/json: examples: order documents: value: order_id: 11111111-1111-1111-1111-111111111111 reference_id: ACC-12345 report: data: JVBERi0xLjQ= content_type: application/pdf filename: test.pdf dicom: data: UEsDBBQ= content_type: application/zip filename: study.zip schema: type: object properties: order_id: type: string format: uuid description: Order ID reference_id: type: string description: Order accession / reference ID report: type: object properties: data: type: string description: Base64-encoded file contents content_type: type: string description: MIME type of the file filename: type: string description: Suggested filename required: - data - content_type - filename dicom: type: object properties: data: type: string description: Base64-encoded file contents content_type: type: string description: MIME type of the file filename: type: string description: Suggested filename required: - data - content_type - filename required: - order_id - reference_id "401": "$ref": "#/components/responses/Unauthorized" "404": "$ref": "#/components/responses/NotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" "/api/v2/order_documents/report": get: operationId: getOrderReport x-mint: href: /api-reference/order-documents/returns-the-radiology-report-pdf-for-an-order summary: Returns the radiology report PDF for an order tags: - Order Documents description: | Returns the base64-encoded radiology report PDF for a single order. Uses the same lookup parameters as `GET /api/v2/order_documents`. security: - BearerAuth: [] parameters: - name: order_id in: query required: false description: Order UUID (one lookup method required) schema: type: string - name: reference_id in: query required: false description: Order accession / reference ID (one lookup method required) schema: type: string - name: patient_name in: query required: false description: Patient full name — use with date_of_birth and study_description schema: type: string - name: date_of_birth in: query required: false description: Patient date of birth (YYYY-MM-DD) — use with patient_name and study_description schema: type: string - name: study_description in: query required: false description: Ambra study description matched via Translation table — use with patient_name and date_of_birth schema: type: string responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: report content: application/json: examples: report: value: order_id: 11111111-1111-1111-1111-111111111111 reference_id: ACC-12345 report: data: JVBERi0xLjQ= content_type: application/pdf filename: test.pdf schema: type: object properties: order_id: type: string format: uuid description: Order ID reference_id: type: string description: Order accession / reference ID report: type: object properties: data: type: string description: Base64-encoded file contents content_type: type: string description: MIME type of the file filename: type: string description: Suggested filename required: - data - content_type - filename required: - order_id - reference_id - report "401": "$ref": "#/components/responses/Unauthorized" "404": "$ref": "#/components/responses/NotFound" "/api/v2/order_documents/dicom": get: operationId: getOrderDicom x-mint: href: /api-reference/order-documents/returns-dicom-imaging-data-for-an-order summary: Returns DICOM imaging data for an order tags: - Order Documents description: | Returns base64-encoded DICOM data for a single order. When no local `dicom_file` is attached, the study is downloaded live from Ambra storage (zip bundle). Uses the same lookup parameters as `GET /api/v2/order_documents`. security: - BearerAuth: [] parameters: - name: order_id in: query required: false description: Order UUID (one lookup method required) schema: type: string - name: reference_id in: query required: false description: Order accession / reference ID (one lookup method required) schema: type: string - name: patient_name in: query required: false description: Patient full name — use with date_of_birth and study_description schema: type: string - name: date_of_birth in: query required: false description: Patient date of birth (YYYY-MM-DD) — use with patient_name and study_description schema: type: string - name: study_description in: query required: false description: Ambra study description matched via Translation table — use with patient_name and date_of_birth schema: type: string responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: dicom content: application/json: examples: dicom: value: order_id: 11111111-1111-1111-1111-111111111111 reference_id: ACC-12345 dicom: data: UEsDBBQ= content_type: application/zip filename: study.zip schema: type: object properties: order_id: type: string format: uuid description: Order ID reference_id: type: string description: Order accession / reference ID dicom: type: object properties: data: type: string description: Base64-encoded file contents content_type: type: string description: MIME type of the file filename: type: string description: Suggested filename required: - data - content_type - filename required: - order_id - reference_id - dicom "401": "$ref": "#/components/responses/Unauthorized" "404": "$ref": "#/components/responses/NotFound" "/api/v2/order_documents/invoices": get: operationId: getOrderInvoices x-mint: href: /api-reference/order-documents/returns-the-invoice-pdf-for-an-order summary: Returns the invoice PDF for an order tags: - Order Documents description: | Returns the base64-encoded invoice PDF for a single order (from the parent appointment). Uses the same lookup parameters as `GET /api/v2/order_documents`. security: - BearerAuth: [] parameters: - name: order_id in: query required: false description: Order UUID (one lookup method required) schema: type: string - name: reference_id in: query required: false description: Order accession / reference ID (one lookup method required) schema: type: string - name: patient_name in: query required: false description: Patient full name — use with date_of_birth and study_description schema: type: string - name: date_of_birth in: query required: false description: Patient date of birth (YYYY-MM-DD) — use with patient_name and study_description schema: type: string - name: study_description in: query required: false description: Ambra study description matched via Translation table — use with patient_name and date_of_birth schema: type: string responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: invoice content: application/json: examples: invoice: value: order_id: 11111111-1111-1111-1111-111111111111 reference_id: ACC-12345 invoice: data: JVBERi0xLjQ= content_type: application/pdf filename: invoice.pdf schema: type: object properties: order_id: type: string format: uuid description: Order ID reference_id: type: string description: Order accession / reference ID invoice: type: object properties: data: type: string description: Base64-encoded file contents content_type: type: string description: MIME type of the file filename: type: string description: Suggested filename required: - data - content_type - filename required: - order_id - reference_id - invoice "401": "$ref": "#/components/responses/Unauthorized" "404": "$ref": "#/components/responses/NotFound" "/api/v2/status": post: operationId: updateVisitStatus x-mint: href: /api-reference/status/updates-the-status-of-a-visit summary: Updates the status of a visit tags: - Status description: | Supply-side endpoint for imaging-center integrations. Updates a visit by accession ID. Supported statuses: `appointment_received` and `no_show`. security: - BearerAuth: [] parameters: [] responses: "429": "$ref": "#/components/responses/TooManyRequests" "500": "$ref": "#/components/responses/InternalServerError" "200": description: status updated successfully content: application/json: examples: appointment_received: value: success: true schema: type: object properties: success: type: boolean description: Status update result required: - success "401": "$ref": "#/components/responses/Unauthorized" "422": "$ref": "#/components/responses/UnprocessableEntity" requestBody: content: application/json: schema: type: object properties: accession_id: type: string description: Visit reference ID (accession number) status: type: string enum: - appointment_received - no_show description: "Status to update. appointment_received: marks visit as booked, no_show: marks visit as no show" start_time: type: string format: date-time description: Appointment start time (required for appointment_received status) required: - accession_id - status required: true /api/v2/testing/fixtures: post: operationId: createSandboxFixtures summary: Bootstrap sandbox fixtures tags: [Testing] security: - BearerAuth: [] responses: "201": description: Known-good sandbox identifiers for this group /api/v2/testing/visits/{visit_id}: patch: operationId: advanceSandboxVisit summary: Advance a sandbox fixture visit to a chosen status tags: [Testing] security: - BearerAuth: [] parameters: - name: visit_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object properties: status: type: string required: [status] responses: "200": description: Visit advanced /api/v2/testing/events: post: operationId: sendSandboxTestEvent summary: Fire a signed test webhook tags: [Testing] security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: event_name: type: string enum: - visit.status_changed - notification.status_changed - referral.auto_book_completed required: [event_name] responses: "202": description: Test event accepted /api/v2/fhir/diagnostic_reports/{id}: get: operationId: getFhirDiagnosticReport summary: Read a FHIR R4 DiagnosticReport tags: [FHIR] security: - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string responses: "200": description: DiagnosticReport /api/v2/fhir/imaging_studies/{id}: get: operationId: getFhirImagingStudy summary: Read a FHIR R4 ImagingStudy tags: [FHIR] security: - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string responses: "200": description: ImagingStudy