> ## 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. # Update or end a coverage > **Permission:** `coverage:write` Change a coverage, or end it. Answers 200 with the coverage. Changing who the coverage is for on a confirmed coverage sends it back to unconfirmed and inactive for staff to confirm again. `coverage_active: false` and `termination_date` end a coverage; `coverage_active: true` is refused (`activation_requires_staff`). The `Idempotency-Key` header is optional. Send JSON; a FHIR Coverage body is refused. ## OpenAPI ````yaml /openapi/ehr-api.v1.yaml patch /v1/clinics/{clinic_id}/coverages/{coverage_id} 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}/coverages/{coverage_id}: patch: tags: - Coverages summary: Update or end a coverage description: >- **Permission:** `coverage:write` Change a coverage, or end it. Answers 200 with the coverage. Changing who the coverage is for on a confirmed coverage sends it back to unconfirmed and inactive for staff to confirm again. `coverage_active: false` and `termination_date` end a coverage; `coverage_active: true` is refused (`activation_requires_staff`). The `Idempotency-Key` header is optional. Send JSON; a FHIR Coverage body is refused. operationId: updateCoverage parameters: - $ref: '#/components/parameters/IdempotencyKeyOptional' - name: clinic_id in: path required: true schema: type: string format: uuid - name: coverage_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CoverageUpdate' responses: '200': description: OK. content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Coverage' idempotent_replay: type: boolean description: >- Present and true when this Idempotency-Key was already used and the original answer is returned. '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: parameters: IdempotencyKeyOptional: name: Idempotency-Key in: header required: false description: >- Optional. A unique value you choose for this request, such as a UUID. When sent, a retry with the same key returns the first answer instead of applying the change twice. See Retries and idempotency. schema: type: string minLength: 1 schemas: CoverageUpdate: type: object additionalProperties: false minProperties: 1 description: >- A change to an existing coverage. Changing who the coverage is for (`payer_id`, `member_id`, `group_number`, `subscriber_member_id`, `relationship_to_subscriber` or the policy holder's name or date of birth) on a confirmed coverage sends it back to `unconfirmed` and inactive until staff confirm it again. Other edits keep its status. `coverage_active: false` and `termination_date` end a coverage; `coverage_active: true` is refused with `activation_requires_staff`. Nothing is ever deleted. Send JSON; a FHIR Coverage body is not accepted. properties: payer_id: type: string format: uuid member_id: type: string maxLength: 200 group_number: type: string maxLength: 200 group_name: type: string maxLength: 200 plan_name: type: string maxLength: 200 coverage_type: type: string enum: - medical - dental - vision - behavioral_health - other payment_responsibility: type: string enum: - P - S - T relationship_to_subscriber: type: string enum: - self - spouse - child - other - employee - organ_donor - cadaver_donor - life_partner subscriber_first_name: type: string maxLength: 200 subscriber_last_name: type: string maxLength: 200 subscriber_date_of_birth: type: string format: date subscriber_gender: type: string enum: - M - F - U subscriber_member_id: type: string maxLength: 200 subscriber_address_line1: type: string maxLength: 200 subscriber_address_city: type: string maxLength: 200 subscriber_address_state: type: string maxLength: 200 subscriber_address_zip: type: string maxLength: 200 coverage_active: type: boolean description: 'Only `false` is accepted: it ends the coverage. `true` is refused.' effective_date: type: string format: date termination_date: type: string format: date copay_amount: type: number minimum: 0 coinsurance_percent: type: number minimum: 0 maximum: 100 deductible_amount: type: number minimum: 0 out_of_pocket_max: type: number minimum: 0 pre_authorization_required: type: boolean network_status: type: string enum: - in_network - out_of_network - unknown is_primary: type: boolean Coverage: type: object description: >- A patient's insurance coverage — the exposed-field allow-list, field by field. A coverage that came in through the API is saved straight away and visible here, but it is `unconfirmed` and `coverage_active` is `false` until clinic staff confirm the payer match; the clinic's own coverages are `confirmed`. Eligibility figures, the clinic's notes and the policy holder's address are never exposed. required: - id - patient_id - coverage_active - verification_status - source properties: id: type: string format: uuid patient_id: type: string format: uuid payer: oneOf: - $ref: '#/components/schemas/CoveragePayer' - type: 'null' member_id: type: - string - 'null' group_number: type: - string - 'null' group_name: type: - string - 'null' plan_name: type: - string - 'null' coverage_type: type: - string - 'null' enum: - medical - dental - vision - behavioral_health - other - null payment_responsibility: type: - string - 'null' enum: - P - S - T - null description: P primary, S secondary, T tertiary. relationship_to_subscriber: type: - string - 'null' enum: - self - spouse - child - other - employee - organ_donor - cadaver_donor - life_partner - null subscriber: oneOf: - $ref: '#/components/schemas/CoverageSubscriber' - type: 'null' is_primary: type: - boolean - 'null' coverage_active: type: boolean description: Always false while `verification_status` is `unconfirmed`. effective_date: type: - string - 'null' format: date termination_date: type: - string - 'null' format: date copay_amount: type: - number - 'null' coinsurance_percent: type: - number - 'null' deductible_amount: type: - number - 'null' out_of_pocket_max: type: - number - 'null' pre_authorization_required: type: - boolean - 'null' network_status: type: - string - 'null' enum: - in_network - out_of_network - unknown - null eligibility: oneOf: - $ref: '#/components/schemas/CoverageEligibility' - type: 'null' verification_status: type: string enum: - confirmed - unconfirmed source: type: string enum: - clinic - api description: '`api` for a coverage that came in through the API.' origin_assistant_name: type: - string - 'null' created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time CoveragePayer: type: object required: - id - display_name properties: id: type: string format: uuid display_name: type: string CoverageSubscriber: type: object description: The policy holder. Their address is not exposed. properties: first_name: type: - string - 'null' last_name: type: - string - 'null' date_of_birth: type: - string - 'null' format: date gender: type: - string - 'null' enum: - M - F - U - null member_id: type: - string - 'null' CoverageEligibility: type: object description: >- The result of the clinic's last eligibility check. It is owned by the clinic's eligibility flow and is never writable through the API. properties: status: type: - string - 'null' checked_at: type: - string - 'null' format: date-time 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). 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`), 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.