> ## Documentation Index > Fetch the complete documentation index at: https://docs.scan.com/llms.txt > Use this file to discover all available pages before exploring further. # Returns a list of patients > Returns a list of patients that are associated with the user group. ## OpenAPI ````yaml /openapi.yaml get /api/v2/patients openapi: 3.1.0 info: title: Scan.com API version: v2 description: > This API provides comprehensive access to Scan.com’s core functionalities, including management of referrals, patient information, authentication, body parts, and imaging modalities. It enables seamless integration for scheduling, data retrieval, and workflow automation within the Scan.com platform, facilitating efficient and secure handling of medical imaging processes. servers: - url: https://api.staging.scan.com description: Sandbox - url: https://api.scan.com description: Production security: - BearerAuth: [] tags: - name: Courier SSO description: >- Mint a one-time Courier portal SSO URL with the same Bearer token used for the rest of the API. - name: Webhooks description: >- Outbound HTTP POST notifications sent to your api_credentials.webhook_url when visit or notification status changes. Configure api_credentials on your LawFirm, Practice, CoordinationGroup, Insurance, Employer, or NurseCaseManagementGroup. - name: Order Documents description: >- Retrieve radiology report PDFs, DICOM imaging, and invoices for orders visible to the authenticated group. - name: Locations description: >- Rank nearby imaging centers for a referral after medical safety answers are on file. Partners submit a preferred center; Scan books the visit. - name: Testing description: Staging-only fixture bootstrap, status advancement, and test webhooks. - name: FHIR description: >- Opt-in FHIR R4 read shapes for DiagnosticReport and ImagingStudy. Not a FHIR server. paths: /api/v2/patients: get: tags: - Patients summary: Returns a list of patients description: | Returns a list of patients that are associated with the user group. operationId: listPatients 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: '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: null 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' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' security: - BearerAuth: [] components: responses: Unauthorized: description: Missing, expired, or wrong-environment token headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: value: error: Unauthorized message: Unauthorized type: authentication_error code: unauthorized request_id: abc-123 documentation_url: https://docs.scan.com/guides/errors#unauthorized expired: value: error: API token expired message: API token expired type: authentication_error code: api_token_expired request_id: abc-123 documentation_url: https://docs.scan.com/guides/errors#api_token_expired TooManyRequests: description: Sandbox request allowance exhausted headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Sandbox request limit reached message: Sandbox request limit reached type: rate_limit_error code: sandbox_request_limit_reached request_id: abc-123 documentation_url: https://docs.scan.com/guides/errors#sandbox_request_limit_reached InternalServerError: description: Unexpected internal error headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Internal server error message: Internal server error type: api_error code: internal_error request_id: abc-123 documentation_url: https://docs.scan.com/guides/errors#internal_error headers: RequestId: description: Correlate this response with Scan support. schema: type: string schemas: ErrorResponse: type: object properties: error: type: string message: type: string type: type: string example: validation_error code: type: string example: unprocessable_entity request_id: type: string documentation_url: type: string errors: type: array items: type: string required: - error - message - type - code securitySchemes: BearerAuth: type: http scheme: bearer description: > `Authorization: Bearer `. Sandbox tokens come from Get API keys and allow 2,000 successful requests or 7 days. Failed 4xx/5xx responses do not consume the allowance. Production tokens are issued from the group's API access tab. ````