> ## 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 referral status counts > Returns aggregate counts for the referrals visible to your group, so you can build dashboards or reconcile totals without paging through `GET /api/v2/referrals`. No extra permission is required. - `total_referrals` is the number of matching referrals. - `referral_status_counts` counts referrals by the top-level (case and billing) `status`. Every status is present, with `0` when no referral has it. The values add up to `total_referrals`. - `visit_status_counts` counts distinct referrals that have at least one visit in each `visits[].status`. Every status is present, with `0` when no referral has it. A referral with visits in two statuses is counted under both, and a referral with no visits is counted under none, so these values can add up to more or less than `total_referrals`. Accepts the same `billable`, `created_date`, `date_of_service`, and `invoice_date` filters as the referral list. ## OpenAPI ````yaml /openapi.yaml get /api/v2/referrals/status_counts openapi: 3.1.0 info: title: Scan.com API version: v2 description: >- The Scan.com Partner API creates imaging referrals, schedules visits, and returns radiology reports. 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: >- Search imaging centers near an address, or rank them for a referral after medical safety answers are on file. Partners submit a preferred center; Scan books the visit. - name: Testing description: Staging-only fixture bootstrap, status advancement, and test webhooks. - name: FHIR description: >- Opt-in FHIR R4 read shapes for DiagnosticReport and ImagingStudy. Not a FHIR server. paths: /api/v2/referrals/status_counts: get: tags: - Referrals summary: Returns referral status counts description: | Returns aggregate counts for the referrals visible to your group, so you can build dashboards or reconcile totals without paging through `GET /api/v2/referrals`. No extra permission is required. - `total_referrals` is the number of matching referrals. - `referral_status_counts` counts referrals by the top-level (case and billing) `status`. Every status is present, with `0` when no referral has it. The values add up to `total_referrals`. - `visit_status_counts` counts distinct referrals that have at least one visit in each `visits[].status`. Every status is present, with `0` when no referral has it. A referral with visits in two statuses is counted under both, and a referral with no visits is counted under none, so these values can add up to more or less than `total_referrals`. Accepts the same `billable`, `created_date`, `date_of_service`, and `invoice_date` filters as the referral list. operationId: getReferralStatusCounts parameters: - 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: invoice_date in: query required: false description: >- Filter by when a visit became invoice ready. Pass one date (YYYY-MM-DD) for that Eastern day, or two dates for an inclusive range. A referral matches if any visit moved to `invoice_ready` in the window. 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: '200': description: referral status counts content: application/json: examples: status counts: value: total_referrals: 3 referral_status_counts: pending: 2 invoice_ready: 1 invoice_sent: 0 canceled: 0 active_case: 0 reductions: 0 closed: 0 collections_pending: 0 active_collections: 0 payment_discrepancy: 0 financed: 0 visit_status_counts: pending: 0 ready_to_book: 0 sent_to_rp: 0 canceled: 0 booked: 2 complete: 0 report_uploaded: 1 contacted_for_booking: 0 sent_to_rad: 0 exam_not_completed: 0 intake_sent: 0 invoice_ready: 1 pending_auth: 0 co_signed: 0 qc_report_ready: 0 schema: type: object properties: total_referrals: type: integer description: Number of referrals that match the filters referral_status_counts: type: object description: >- Referrals per top-level `status`. Every status is present, with `0` for statuses that have no referrals. Values add up to `total_referrals`. additionalProperties: type: integer visit_status_counts: type: object description: >- Distinct referrals with at least one visit in each `visits[].status`. Every status is present, with `0` for statuses that have no referrals. Values can add up to more or less than `total_referrals`. additionalProperties: type: integer '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 `. Reuse the same token on later requests until it expires or is revoked. Do not request a new token for each call. The token does not expire after 24 hours. Sandbox tokens come from Get API keys and allow 2,000 successful requests or 7 days, or 90 days with an access code. Failed 4xx/5xx responses do not consume the allowance. Production tokens are issued from the group's API access tab and last until the expiry set there, or until revoked when no expiry is set. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.