> ## 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. # Submit an insurance claim > **Permission:** `insurance.claims:submit` Submit a claim to one of the clinic's insurers. For a clinic-owned key, or an organization with NO insurer link (a developer). An organization linked to an insurer is refused (`role_required`): an insurer does not submit claims to itself. The claim is saved as `submitted`, answers 201 with the claim and its lines, and carries no money. The `Idempotency-Key` header is REQUIRED - a retry with the same key returns the original claim, never a second one. ## OpenAPI ````yaml /openapi/ehr-api.v1.yaml post /v1/clinics/{clinic_id}/insurance/claims 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/claims: post: tags: - HMO insurance summary: Submit an insurance claim description: >- **Permission:** `insurance.claims:submit` Submit a claim to one of the clinic's insurers. For a clinic-owned key, or an organization with NO insurer link (a developer). An organization linked to an insurer is refused (`role_required`): an insurer does not submit claims to itself. The claim is saved as `submitted`, answers 201 with the claim and its lines, and carries no money. The `Idempotency-Key` header is REQUIRED - a retry with the same key returns the original claim, never a second one. operationId: submitInsuranceClaim parameters: - $ref: '#/components/parameters/IdempotencyKeyRequired' - name: clinic_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InsuranceClaimSubmit' responses: '201': description: Created - submitted, with its lines and no money recorded. content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/InsuranceClaim' 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: IdempotencyKeyRequired: name: Idempotency-Key in: header required: true description: >- A unique value you choose for this request, such as a UUID. Sending the same key again returns the first answer instead of doing the work twice, so a timed-out request is safe to retry. Reusing a key for a different request is refused with `409 idempotency_key_conflict`, and retrying while the first request is still running with `409 idempotency_key_reused`. See Retries and idempotency. schema: type: string minLength: 1 schemas: InsuranceClaimSubmit: type: object additionalProperties: false description: >- A claim to submit to one of the clinic's insurers for a patient. It is saved as `submitted` with no money on it. `patient_id` must be a patient your organization is linked to (a clinic-owned key may use any of its clinic's patients). There is no field for a paid or written-off amount; sending one is refused as an unknown field. required: - patient_id - insurance_company_id - service_date_from - items properties: patient_id: type: string format: uuid insurance_company_id: type: string format: uuid enrollee_id: type: string format: uuid description: Must be an enrollee of that patient with that insurer. claim_type: type: string enum: - outpatient - inpatient - emergency - pharmacy - lab - radiology - dental - optical - other default: outpatient service_date_from: type: string format: date-time service_date_to: type: string format: date-time admission_date: type: string format: date-time discharge_date: type: string format: date-time pa_code: type: string maxLength: 100 diagnoses: type: array maxItems: 20 items: $ref: '#/components/schemas/InsuranceDiagnosisInput' items: type: array minItems: 1 maxItems: 200 items: $ref: '#/components/schemas/InsuranceClaimSubmitItem' InsuranceClaim: type: object description: >- A claim the clinic submitted to an insurer. `status` is the clinic-side lifecycle (`submitted`, `approved`, `partially_approved`, `denied`, `partially_paid`, `paid`, ...); `hmo_status` is the insurer's verdict (`PENDING`, `APPROVED`, `PARTIALLY_APPROVED`, `REJECTED`). `paid_amount` and `written_off_amount` are what the CLINIC has recorded - no API call changes them. `items`, `diagnoses` and `documents` are on the single-claim read only. The clinic's notes and internal analysis are never exposed. required: - id - claim_number - insurance_company_id - status properties: id: type: string format: uuid claim_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 pre_auth_ids: type: array items: type: string format: uuid pa_code: type: - string - 'null' claim_type: type: - string - 'null' enum: - outpatient - inpatient - emergency - pharmacy - lab - radiology - dental - optical - other - null status: type: string hmo_status: type: - string - 'null' enum: - PENDING - APPROVED - PARTIALLY_APPROVED - REJECTED - null currency: type: - string - 'null' amount_billed: type: - number - 'null' amount_approved: type: - number - 'null' paid_amount: type: - number - 'null' written_off_amount: type: - number - 'null' patient_responsibility: type: - number - 'null' service_date_from: type: - string - 'null' format: date-time service_date_to: type: - string - 'null' format: date-time admission_date: type: - string - 'null' format: date-time discharge_date: type: - string - 'null' format: date-time is_floating: type: - boolean - 'null' submitted_at: type: - string - 'null' format: date-time vetted_at: type: - string - 'null' format: date-time approved_at: type: - string - 'null' format: date-time paid_at: type: - string - 'null' format: date-time denial_reason: type: - string - 'null' denial_code: type: - string - 'null' created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time items: type: array items: $ref: '#/components/schemas/InsuranceClaimItem' diagnoses: type: array items: $ref: '#/components/schemas/InsuranceDiagnosis' documents: type: array items: $ref: '#/components/schemas/InsuranceClaimDocument' InsuranceDiagnosisInput: type: object additionalProperties: false required: - icd_code properties: icd_code: type: string maxLength: 20 name: type: string maxLength: 300 is_primary: type: boolean InsuranceClaimSubmitItem: type: object additionalProperties: false required: - description - unit_price properties: description: type: string maxLength: 300 item_type: type: string enum: - consultation - procedure - medication - lab_test - imaging - radiology - service - equipment - hospitalization - room_charge - other default: service tariff_code: type: string maxLength: 100 quantity: type: integer minimum: 1 maximum: 100000 default: 1 unit_price: type: number minimum: 0 service_date: type: string format: date-time InsuranceClaimItem: type: object description: >- A line of a claim. `*_billed` is what the clinic billed; `*_approved` is what the insurer approved (null until vetted). `hmo_item_status` is `PENDING`, `APPROVED`, `ADJUSTED` or `DECLINED`. properties: id: type: string format: uuid item_type: type: - string - 'null' description: type: - string - 'null' tariff_code: type: - string - 'null' service_date: type: - string - 'null' format: date-time qty_billed: type: - number - 'null' unit_price_billed: type: - number - 'null' sub_total_billed: type: - number - 'null' qty_approved: type: - number - 'null' unit_price_approved: type: - number - 'null' sub_total_approved: type: - number - 'null' hmo_item_status: type: - string - 'null' enum: - PENDING - APPROVED - ADJUSTED - DECLINED - null denial_reason: type: - string - 'null' comments: type: array items: type: string benefit_label: type: - string - 'null' InsuranceDiagnosis: type: object required: - icd_code properties: icd_code: type: string name: type: - string - 'null' is_primary: type: - boolean - 'null' InsuranceClaimDocument: type: object description: >- Metadata of a document attached to a claim. The file itself is not served by this API. properties: id: type: string format: uuid document_type: type: - string - 'null' file_name: type: - string - 'null' mime_type: type: - string - 'null' file_size: type: - number - 'null' document_date: type: - string - 'null' format: date-time description: type: - string - '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.