> ## Documentation Index > Fetch the complete documentation index at: https://docs.maxcare.ai/llms.txt > Use this file to discover all available pages before exploring further. # List visit reasons > The reason-for-visit catalogue. `supported: false` (with an empty list) means this organization's EHR folds the reason into the appointment type — an app should hide its reason picker rather than show an empty one. ## OpenAPI ````yaml /openapi-v3.json get /visit-reasons openapi: 3.0.0 info: title: Max AI Public API description: API for third-party marketplace apps version: '3.0' contact: {} servers: - url: https://api.maxcare.ai/v3 security: [] tags: [] paths: /visit-reasons: get: tags: - Schedule summary: List visit reasons description: >- The reason-for-visit catalogue. `supported: false` (with an empty list) means this organization's EHR folds the reason into the appointment type — an app should hide its reason picker rather than show an empty one. operationId: VisitReasonsPublicController_listVisitReasons parameters: - name: page required: false in: query description: Page number (1-indexed) schema: default: 1 example: 1 - name: pageSize required: false in: query description: Number of items per page (max 100) schema: default: 100 example: 100 - name: facilityId required: false in: query description: >- Facility ID (fac_…) selecting the EHR instance whose catalogue to read schema: type: string - name: active required: false in: query description: Only return types the practice has left active schema: type: boolean example: true - name: X-Organization-Id in: header required: true schema: type: string description: Target clinic organization ID responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ListVisitReasonsSuccessResponse' '400': description: Missing or invalid request parameter content: application/json: schema: $ref: '#/components/schemas/PublicApiBadRequestResponse' '401': description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/PublicApiUnauthorizedResponse' '403': description: Insufficient scope content: application/json: schema: $ref: '#/components/schemas/PublicApiForbiddenResponse' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/PublicApiRateLimitResponse' '502': description: EHR sync failed content: application/json: schema: $ref: '#/components/schemas/PublicApiBadGatewayResponse' '503': description: EHR integration unavailable content: application/json: schema: $ref: '#/components/schemas/PublicApiServiceUnavailableResponse' security: - api-key: [] components: schemas: ListVisitReasonsSuccessResponse: type: object properties: code: type: string description: Response code example: success data: $ref: '#/components/schemas/ListVisitReasonsData' required: - code - data PublicApiBadRequestResponse: type: object properties: code: type: string description: Error code example: bad_request message: type: string description: Human-readable error message example: '''id'' must be a valid UUID' trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiUnauthorizedResponse: type: object properties: code: type: string description: Error code example: unauthorized message: type: string description: Human-readable error message example: Invalid or missing API key trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiForbiddenResponse: type: object properties: code: type: string description: Error code example: forbidden message: type: string description: Human-readable error message example: Insufficient scope trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiRateLimitResponse: type: object properties: code: type: string description: Error code example: rate_limit_exceeded message: type: string description: Human-readable error message example: Rate limit exceeded. Maximum 1000 requests per 60 seconds. trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiBadGatewayResponse: type: object properties: code: type: string description: Error code example: unexpected_integration_error message: type: string description: Human-readable error message example: EHR sync failed trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiServiceUnavailableResponse: type: object properties: code: type: string description: Error code example: server_unresponsive message: type: string description: Human-readable error message example: EHR integration is not available for this note trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id ListVisitReasonsData: type: object properties: visitReasons: description: >- Empty on EHRs that fold the visit reason into the appointment type (EZDerm) type: array items: $ref: '#/components/schemas/VisitReasonResponse' pagination: $ref: '#/components/schemas/PaginationInfoResponse' meta: $ref: '#/components/schemas/FreshnessMetaResponse' supported: type: boolean description: >- Whether this organization's EHR models visit reasons as a separate catalogue at all example: true required: - visitReasons - pagination - meta - supported VisitReasonResponse: type: object properties: id: type: string example: vrs_9f2c1d0e3b4a5968778695a4b3c2d1e0 externalId: type: string example: '441' name: type: string example: Annual skin check active: type: boolean example: true required: - id - externalId - name - active PaginationInfoResponse: type: object properties: page: type: number description: Current page number example: 1 pageSize: type: number description: Items per page example: 100 totalCount: type: number description: Total number of items example: 250 totalPages: type: number description: Total number of pages example: 3 required: - page - pageSize - totalCount - totalPages FreshnessMetaResponse: type: object properties: sourceSyncedAt: type: string description: >- When the underlying data was last synced from, or read from, the EHR. Null means complete sync coverage for the requested scope and dates is unknown. Read `sourceKind` before treating this as a lag measurement — on a live read it is the moment of the read itself, so `now - sourceSyncedAt` is always ~0 and measures nothing. nullable: true example: '2026-07-26T12:59:31.000Z' sourceKind: type: string enum: - live_read - mirror description: >- What `sourceSyncedAt` actually is. `live_read`: the endpoint went to the EHR for this request, so the timestamp is the read time and there is no lag to measure. `mirror`: the timestamp is a real sync watermark and `now - sourceSyncedAt` IS the lag. Slot searches use `mirror` unless strong consistency is requested. A consumer computing mirror lag must skip `live_read` responses rather than average a structural zero into its numbers. example: live_read maxStalenessSeconds: type: number description: The staleness this endpoint is designed to stay within, in seconds example: 60 strongConsistency: type: boolean description: >- Whether the response bypassed caches and read the EHR live (`?consistency=strong`) example: false required: - sourceSyncedAt - sourceKind - maxStalenessSeconds - strongConsistency securitySchemes: api-key: scheme: bearer bearerFormat: JWT type: http description: Marketplace API key ````