> ## 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 prior authorizations > Returns a paginated list of prior authorizations with visit counts, validity window, CPT linkage, and the linked insurance policy. Requires read:prior_authorizations scope. ## OpenAPI ````yaml /openapi-v1.json get /prior-authorizations openapi: 3.0.0 info: title: Max AI Public API description: API for third-party marketplace apps version: '1.0' contact: {} servers: - url: https://api.maxcare.ai/v1 security: [] tags: [] paths: /prior-authorizations: get: tags: - Prior Authorizations summary: List prior authorizations description: >- Returns a paginated list of prior authorizations with visit counts, validity window, CPT linkage, and the linked insurance policy. Requires read:prior_authorizations scope. operationId: PriorAuthorizationsPublicController_listPriorAuthorizations 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: patientId required: false in: query description: Filter by patient ID (UUID) schema: example: 8de03039-3a9e-417a-b2b3-a8b8df183631 type: string - name: insurancePolicyId required: false in: query description: Filter by insurance policy ID (UUID) schema: example: a1b2c3d4-5678-4abc-9def-0123456789ab type: string - name: activeOnly required: false in: query description: >- Only return authorizations active in the EHR. Defaults to false (all). schema: type: boolean example: true - name: validOn required: false in: query description: >- Only return authorizations whose start/end window covers this date (ISO 8601) schema: example: '2026-08-01' type: string - name: sortBy required: false in: query description: Sort field schema: example: startDate enum: - createdAt - updatedAt - startDate - endDate type: string - name: sortOrder required: false in: query description: Sort direction schema: example: desc enum: - asc - desc type: string - 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/ListPriorAuthorizationsSuccessResponse' '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' security: - api-key: [] components: schemas: ListPriorAuthorizationsSuccessResponse: type: object properties: code: type: string description: Response code example: success data: $ref: '#/components/schemas/ListPriorAuthorizationsResponseData' required: - code - data 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 ListPriorAuthorizationsResponseData: type: object properties: priorAuthorizations: type: array items: $ref: '#/components/schemas/ExternalPriorAuthorizationResponse' pagination: $ref: '#/components/schemas/PaginationInfoResponse' required: - priorAuthorizations - pagination ExternalPriorAuthorizationResponse: type: object properties: id: type: string description: Prior authorization unique identifier example: a1b2c3d4-5678-4abc-9def-0123456789ab authorizationNumber: type: string description: Payer-issued authorization number example: AUTH123456 insurancePolicyId: type: string description: Insurance policy ID this authorization belongs to nullable: true example: b2c3d4e5-6789-4bcd-aef0-123456789abc patientId: type: string description: >- Patient ID this authorization belongs to (resolved through the policy) nullable: true example: 8de03039-3a9e-417a-b2b3-a8b8df183631 startDate: type: string description: Authorization window start date nullable: true example: '2026-01-01T00:00:00.000Z' endDate: type: string description: Authorization window end date nullable: true example: '2026-12-31T00:00:00.000Z' numVisits: type: number description: Approved number of visits nullable: true example: 12 numRemaining: type: number description: Remaining number of visits nullable: true example: 7 active: type: boolean description: Whether the authorization is currently active/valid in the EHR example: true cptCodes: description: >- CPT codes the authorization covers (drug/procedure linkage). Populated for EZDerm; null for ModMed. nullable: true example: - J0178 - '67028' type: array items: type: string authType: type: string description: >- Authorization type as reported by the EHR (ModMed only, e.g. 'Authorization', 'Referral') nullable: true example: Authorization description: type: string description: Free-text description / note nullable: true terminatedAt: type: string description: When the authorization disappeared from the EHR (soft delete) nullable: true example: null source: type: string description: EHR source nullable: true enum: - modmed - ezderm createdAt: type: string description: Created timestamp example: '2026-03-20T18:35:10.209Z' updatedAt: type: string description: Last updated timestamp example: '2026-03-23T03:15:47.285Z' required: - id - authorizationNumber - insurancePolicyId - patientId - startDate - endDate - numVisits - numRemaining - active - cptCodes - authType - description - terminatedAt - source - createdAt - updatedAt 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 securitySchemes: api-key: scheme: bearer bearerFormat: JWT type: http description: Marketplace API key ````