> ## 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. # Open an encounter > **Permission:** `encounters:write` Open a visit as a draft note. Opens a visit for a patient as a DRAFT note a clinician completes, and answers 201 Created with the encounter (`status: draft`, `review_status: pending`). Nothing is ordered, prescribed, signed, locked or billed, and no note text can be sent; the draft appears in the clinic's consultation list for a clinician to finish. A restricted patient is a 404. The `Idempotency-Key` header is REQUIRED — a retry with the same key returns the original encounter, never a second draft. Send JSON; a FHIR Encounter body is refused. ## OpenAPI ````yaml /openapi/ehr-api.v1.yaml post /v1/clinics/{clinic_id}/encounters 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}/encounters: post: tags: - Encounters summary: Open an encounter description: >- **Permission:** `encounters:write` Open a visit as a draft note. Opens a visit for a patient as a DRAFT note a clinician completes, and answers 201 Created with the encounter (`status: draft`, `review_status: pending`). Nothing is ordered, prescribed, signed, locked or billed, and no note text can be sent; the draft appears in the clinic's consultation list for a clinician to finish. A restricted patient is a 404. The `Idempotency-Key` header is REQUIRED — a retry with the same key returns the original encounter, never a second draft. Send JSON; a FHIR Encounter body is refused. operationId: createEncounter 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/EncounterCreate' responses: '201': description: Created — a draft visit note awaiting a clinician. content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Encounter' idempotent_replay: type: boolean description: >- Present and true when this Idempotency-Key was already used and the original encounter 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: EncounterCreate: type: object additionalProperties: false description: >- A visit to open for a patient. It opens a DRAFT note for a clinician to complete: nothing is ordered, prescribed, signed, locked or billed, and no note text can be sent (there is no field for it). The draft appears in the clinic's consultation list for the clinician to finish. `clinician_id` must be a clinician the clinic lists (see `GET …/note-clinicians`). The `Idempotency-Key` header is REQUIRED. Send JSON; a FHIR Encounter body is not accepted. required: - patient_id - clinician_id properties: patient_id: type: string format: uuid clinician_id: type: string format: uuid class: type: string enum: - ambulatory - emergency - inpatient - virtual - home_health started_at: type: string format: date-time ended_at: type: string format: date-time description: Must not be before `started_at`. reason: type: string minLength: 1 maxLength: 500 description: The administrative reason for the visit — not clinical note text. origin_assistant_name: type: string maxLength: 200 description: Name of the assistant or connected app that opened the visit. Encounter: type: object description: >- A visit as documented in the clinic: a clinical note seen as a visit — the exposed-field allow-list, field by field. The `id` is the note's id, so the same visit reads under Notes. It carries the visit's status, dates, administrative reason and clinician only: no note text, title, diagnosis, plan, service, signature or billing is ever exposed here (clinical text is read through Notes). Every encounter is a `consultation`; triage, ward and appointment records are not encounters in this API. A visit opened through the API is a `draft` with `review_status: pending` until a clinician has reviewed it. required: - id - patient_id - kind - status - period - source - review_status properties: id: type: string format: uuid description: The visit note's id. patient_id: type: string format: uuid kind: type: string enum: - consultation status: type: string enum: - draft - completed description: >- `draft` until a clinician signs, locks or finalizes the note; `completed` after. class: type: - string - 'null' enum: - ambulatory - emergency - inpatient - virtual - home_health - null description: Null when no class was recorded for the visit. period: type: object required: - start - end properties: start: type: - string - 'null' format: date-time end: type: - string - 'null' format: date-time reason: type: - string - 'null' description: >- The administrative reason for the visit (at most 500 characters), not note text. clinician_id: type: - string - 'null' format: uuid description: >- The clinician's id as listed by `GET …/providers` and `GET …/note-clinicians`. source: type: string enum: - clinic - api description: '`api` for a visit opened through the API.' origin_assistant_name: type: - string - 'null' review_status: type: string enum: - pending - confirmed description: >- `confirmed` for a visit the clinic opened itself, and for an API draft once a clinician has reviewed it. created_at: type: - string - 'null' format: date-time updated_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.