> ## Documentation Index > Fetch the complete documentation index at: https://docs.clinikehr.com/llms.txt > Use this file to discover all available pages before exploring further. # List pre-authorization requests > **Permission:** `insurance.pa:read` List pre-authorization requests sent to your insurer. Requests the clinic has sent for authorization (and their outcome). Requests still in the clinic's draft or review stages are never shown to an insurer. A clinic-owned key sees all of its clinic's requests. ## OpenAPI ````yaml /openapi/ehr-api.v1.yaml get /v1/clinics/{clinic_id}/insurance/pre-authorizations openapi: 3.1.0 info: title: ClinikEHR API version: 1.0.0 description: >- Server-to-server REST API for a clinic's own data, reached with a key the clinic (or a developer workspace) creates in the developer portal. Authenticate every request with `Authorization: Bearer `. Test keys reach only your workspace's own synthetic sandbox; live keys reach the clinic that created them. Lists wrap their rows as `{ data, has_more, next_cursor }`; single resources are returned directly. Errors are `application/problem+json` (RFC 9457) with a stable `code`. Write requests accept an `Idempotency-Key` header so a retry never repeats a change. See the guides for authentication, permissions, pagination, rate limits and retries. servers: - url: https://api.clinikehr.com security: - ApiKey: [] paths: /v1/clinics/{clinic_id}/insurance/pre-authorizations: get: tags: - HMO insurance summary: List pre-authorization requests description: >- **Permission:** `insurance.pa:read` List pre-authorization requests sent to your insurer. Requests the clinic has sent for authorization (and their outcome). Requests still in the clinic's draft or review stages are never shown to an insurer. A clinic-owned key sees all of its clinic's requests. operationId: listInsurancePreAuthorizations parameters: - name: clinic_id in: path required: true schema: type: string format: uuid - name: insurance_company_id in: query required: false schema: type: string format: uuid - name: status in: query required: false schema: type: string enum: - draft - ai_reviewed - reviewed - sent_for_authorization - approved - denied - expired - cancelled - name: updated_since in: query required: false schema: type: string format: date-time - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 25 - name: starting_after in: query required: false schema: type: string format: uuid responses: '200': description: OK. content: application/json: schema: type: object required: - data - has_more - next_cursor properties: data: type: array items: $ref: '#/components/schemas/InsurancePreAuthorization' has_more: type: boolean next_cursor: type: - string - 'null' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/TooManyRequests' security: - ApiKey: [] components: schemas: InsurancePreAuthorization: type: object description: >- A pre-authorization request the clinic sent to an insurer. `status` is `sent_for_authorization` until the insurer decides, then `approved` or `denied` (with `pa_code` on approval). `items` and `diagnoses` are on the single read only. required: - id - request_number - insurance_company_id - status properties: id: type: string format: uuid request_number: type: string insurance_company_id: type: string format: uuid insurance_plan_id: type: - string - 'null' format: uuid enrollee_id: type: - string - 'null' format: uuid patient_id: type: string format: uuid encounter_id: type: - string - 'null' format: uuid request_type: type: - string - 'null' enum: - service - procedure - medication - equipment - hospitalization - consultation - lab_test - null priority_level: type: - string - 'null' enum: - routine - urgent - emergency - null status: type: string enum: - draft - ai_reviewed - reviewed - sent_for_authorization - approved - denied - expired - cancelled estimated_cost: type: - number - 'null' approved_amount: type: - number - 'null' pa_code: type: - string - 'null' pr_code: type: - string - 'null' is_approved: type: - boolean - 'null' is_handled: type: - boolean - 'null' handled_at: type: - string - 'null' format: date-time rejection_reason: type: - string - 'null' encounter_date: type: - string - 'null' format: date-time admission_start: type: - string - 'null' format: date-time admission_end: type: - string - 'null' format: date-time is_floating: type: - boolean - 'null' submitted_at: type: - string - 'null' format: date-time created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time items: type: array items: $ref: '#/components/schemas/InsurancePreAuthorizationItem' diagnoses: type: array items: $ref: '#/components/schemas/InsuranceDiagnosis' InsurancePreAuthorizationItem: type: object properties: id: type: string format: uuid item_type: type: - string - 'null' description: type: - string - 'null' tariff_code: type: - string - 'null' quantity: type: - number - 'null' unit_cost: type: - number - 'null' total_cost: type: - number - 'null' diagnosis: type: - string - 'null' icd_cpt_code: type: - string - 'null' medical_necessity: type: - string - 'null' approval_status: type: - string - 'null' is_approved: type: - boolean - 'null' reject_reason: type: - string - 'null' InsuranceDiagnosis: type: object required: - icd_code properties: icd_code: type: string name: type: - string - 'null' is_primary: type: - boolean - 'null' Problem: type: object description: RFC 9457 application/problem+json. required: - type - title - status - code - request_id properties: type: type: string format: uri title: type: string status: type: integer detail: type: string code: type: string request_id: type: string errors: type: array items: type: object required: - pointer - message properties: pointer: type: string message: type: string responses: BadRequest: description: >- The request failed validation (unknown query parameter, limit out of range, malformed body, or a write-off sent without its reason — `reason_required`). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Unauthorized: description: >- Missing, malformed, unknown, revoked or expired key, or the wrong secret. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Forbidden: description: >- The key or connection lacks the required scope, the plan does not include this resource, the request came from an address this key's IP allow-list does not permit, a TEST-environment workspace key asked for a clinic_id other than its own workspace's sandbox (`sandbox_only`), or a LIVE workspace key asked for a real clinic while its workspace's verification has lapsed (`not_verified`) — the response never names which addresses ARE allowed, nor which clinic actually is the sandbox. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' NotFound: description: The record is absent, or out of the key's scope — one message for both. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Conflict: description: >- The request is well-formed but conflicts with the CURRENT STATE of the record — a double-booked slot (`slot_taken`), a clinician's calendar blocked at that time (`out_of_office`), nobody eligible free (`no_provider_available`), an item that still has stock (`item_has_stock`), an item that has been used and so cannot be deleted (`item_has_history`), a ledger movement that cannot be covered (`insufficient_stock`, `expired_stock_not_transferable`), a note already signed or clinician-touched (`note_not_editable`), an Idempotency-Key already used for a different request or still in flight (`idempotency_key_conflict`, `idempotency_key_reused`), or an external-stock batch rejected as structurally invalid or a suspicious shrink versus the clinic's last accepted batch (`batch_rejected`), or an outside record that conflicts with what was already submitted or decided: the same `client_reference` sent again with different content (`client_reference_conflict`), or a submission a clinician has already decided (`submission_not_pending`), or an insurance write that conflicts with the clinic's setup or the coverage's state: the patient already has a coverage for that payer (`coverage_exists`, the existing coverage's id is in `detail` when the caller can see that patient), a payer the clinic has not enabled in Settings → Insurance (`payer_not_enabled`), or `coverage_active: true` sent through the API (`activation_requires_staff` — only clinic staff activate a coverage), or a change to an outside care provider the clinic added rather than an app (`care_provider_clinic_managed` — only the clinic can change or remove it). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' TooManyRequests: description: Rate limited. See the Retry-After header. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: ehr_live__ or ehr_test__ ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.