> ## 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. # Create a patient > **Permission:** `patients:write` Create a patient. Possible duplicates are flagged for staff review, never silently merged or refused. run_automations defaults false, suppressing the patient.created Agent Studio dispatch. ## OpenAPI ````yaml /openapi/ehr-api.v1.yaml post /v1/clinics/{clinic_id}/patients 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}/patients: post: tags: - Patients summary: Create a patient description: >- **Permission:** `patients:write` Create a patient. Possible duplicates are flagged for staff review, never silently merged or refused. run_automations defaults false, suppressing the patient.created Agent Studio dispatch. operationId: createPatient 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/PatientCreateRequest' responses: '200': description: >- OK. `data` carries `duplicate_candidates` alongside the created record when a possible match was found. content: application/json: schema: type: object required: - data properties: data: allOf: - $ref: '#/components/schemas/Patient' - type: object properties: duplicate_candidates: type: array items: type: object properties: id: type: string format: uuid mrn: type: - string - 'null' first_name: type: - string - 'null' last_name: type: - string - 'null' similarity: type: - number - '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: 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: PatientCreateRequest: type: object description: >- Unknown top-level fields, and every named read-only field (mrn, portal_access_enabled, admission_status, client_status, insurance, pharmacies, care_providers, couple, profile_image, notification_settings — the last refused with the distinct code notification_settings_not_writable), are refused BY NAME, never silently dropped — enforced by the database, not this schema. `allergies`, `current_medications` and `chronic_conditions` are not accepted here either: they are the clinic's reviewed clinical record, so they are refused by name. Send allergies to `createAllergy` and conditions to `createCondition`; each is held for a clinician to confirm. They are still returned when you read a patient. required: - first_name - last_name - client_type properties: first_name: type: string minLength: 1 last_name: type: string minLength: 1 middle_name: type: string preferred_name: type: string title: type: string suffix: type: string client_type: type: string enum: - adult - minor date_of_birth: type: string format: date gender: type: string enum: - male - female - other marital_status: type: string enum: - single - married - divorced - widowed - separated email: type: string format: email phone: type: string secondary_phone: type: string country: type: string nationality: type: string occupation: type: string residential_address: type: string work_address: type: string city: type: string state: type: string zip: type: string next_of_kin: $ref: '#/components/schemas/NextOfKin' national_id: type: string preferred_language: type: string referred_by: type: string referral_source_id: type: string format: uuid employment: $ref: '#/components/schemas/Employment' is_dependent: type: boolean is_waitlist: type: boolean sponsor_id: type: string format: uuid billing: $ref: '#/components/schemas/PatientBilling' medical_history: type: string blood_type: type: string enum: - O+ - O- - A+ - A- - B+ - B- - AB+ - AB- genotype: type: string enum: - AA - AS - SS - AC - SC family_history: type: string smoking_status: type: string alcohol_use: type: string recreational_drug_use: type: string physical_activity: type: string living_arrangement: type: string status: type: string enum: - active - prospect - inactive - blocked is_vip: type: boolean primary_location_id: type: string format: uuid emails: type: array items: $ref: '#/components/schemas/PatientEmail' phones: type: array items: $ref: '#/components/schemas/PatientPhone' guardians: type: array items: $ref: '#/components/schemas/PatientGuardian' run_automations: type: boolean default: false description: Default false suppresses the patient.created Agent Studio dispatch. Patient: type: object required: - id - first_name - last_name properties: id: type: string format: uuid mrn: type: - string - 'null' first_name: type: string last_name: type: string middle_name: type: - string - 'null' preferred_name: type: - string - 'null' title: type: - string - 'null' suffix: type: - string - 'null' date_of_birth: type: - string - 'null' format: date gender: type: - string - 'null' enum: - male - female - other - null marital_status: type: - string - 'null' enum: - single - married - divorced - widowed - separated - null client_type: type: - string - 'null' enum: - adult - minor - couple - null client_status: type: - string - 'null' description: Read-only global status (patients.client_status). is_dependent: type: boolean email: type: - string - 'null' phone: type: - string - 'null' secondary_phone: type: - string - 'null' country: type: - string - 'null' nationality: type: - string - 'null' occupation: type: - string - 'null' residential_address: type: - string - 'null' work_address: type: - string - 'null' city: type: - string - 'null' state: type: - string - 'null' zip: type: - string - 'null' next_of_kin: $ref: '#/components/schemas/NextOfKin' national_id: type: - string - 'null' preferred_language: type: - string - 'null' referred_by: type: - string - 'null' referral_source_id: type: - string - 'null' format: uuid employment: $ref: '#/components/schemas/Employment' is_waitlist: type: boolean billing: $ref: '#/components/schemas/PatientBilling' sponsor_id: type: - string - 'null' format: uuid allergies: type: array items: type: string medical_history: type: - string - 'null' current_medications: type: array items: type: string chronic_conditions: type: array items: type: string blood_type: type: - string - 'null' enum: - O+ - O- - A+ - A- - B+ - B- - AB+ - AB- - null genotype: type: - string - 'null' enum: - AA - AS - SS - AC - SC - null family_history: type: - string - 'null' smoking_status: type: - string - 'null' alcohol_use: type: - string - 'null' recreational_drug_use: type: - string - 'null' physical_activity: type: - string - 'null' living_arrangement: type: - string - 'null' has_profile_image: type: boolean description: >- Read-only. Whether the patient has a profile picture on file. The picture itself is not available through the API yet. profile_image_path: type: - string - 'null' description: >- Read-only. Not available through the API yet - this value cannot be used to download the picture. status: type: - string - 'null' enum: - active - prospect - inactive - blocked - null is_vip: type: boolean primary_location_id: type: - string - 'null' format: uuid portal_access_enabled: type: - boolean - 'null' description: Read-only. admission_status: type: - string - 'null' description: Read-only, ward-only. couple: oneOf: - $ref: '#/components/schemas/PatientCouple' - type: 'null' emails: type: array items: $ref: '#/components/schemas/PatientEmail' description: Write REPLACES the whole set. phones: type: array items: $ref: '#/components/schemas/PatientPhone' description: Write REPLACES the whole set. guardians: type: array items: $ref: '#/components/schemas/PatientGuardian' description: Write REPLACES the whole set. Only accepted when client_type=minor. insurance: type: array items: type: object description: Read-only. Own module, own save action — never written here. pharmacies: type: array items: type: object description: Read-only. Populated by intake extraction only. care_providers: type: array items: type: object description: Read-only. Populated by intake extraction only. notification_settings: oneOf: - $ref: '#/components/schemas/PatientNotificationSettings' - type: 'null' created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time NextOfKin: type: object properties: name: type: - string - 'null' phone: type: - string - 'null' address: type: - string - 'null' Employment: type: object properties: status: type: - string - 'null' company: type: - string - 'null' role: type: - string - 'null' PatientBilling: type: object properties: individual_type: type: - string - 'null' enum: - self_pay - insurance - null group_type: type: - string - 'null' enum: - self_pay - insurance - null PatientEmail: type: object required: - email properties: email: type: string format: email type: type: - string - 'null' permission: type: - string - 'null' enum: - email_ok - no_email - null is_primary: type: boolean default: false PatientPhone: type: object required: - phone_number properties: phone_number: type: string type: type: - string - 'null' permission: type: - string - 'null' enum: - text_voicemail_ok - text_ok - voicemail_ok - no_call - null is_primary: type: boolean default: false PatientGuardian: type: object properties: guardian_id: type: - string - 'null' format: uuid first_name: type: - string - 'null' last_name: type: - string - 'null' email: type: - string - 'null' phone: type: - string - 'null' relationship: type: - string - 'null' enum: - parent - grandparent - sibling - aunt_uncle - legal_guardian - foster_parent - step_parent - other - null is_responsible_for_billing: type: boolean default: false is_primary: type: boolean default: false can_access_records: type: boolean default: false is_emergency_contact: type: boolean default: true can_schedule_appointments: type: boolean default: false notes: type: - string - 'null' PatientCouple: type: object description: >- Read-only — a couple registration is a separate two-patient transaction this API does not perform. properties: partner_id: type: - string - 'null' format: uuid responsible_for_billing: type: - boolean - 'null' relationship_status: type: - string - 'null' PatientNotificationSettings: type: object description: >- Read-only — refused (notification_settings_not_writable) if sent on a write. properties: upcoming_appointments_enabled: type: - boolean - 'null' upcoming_appointments_email_option: type: - string - 'null' upcoming_appointments_phone_option: type: - string - 'null' incomplete_documents_enabled: type: - boolean - 'null' incomplete_documents_email_option: type: - string - 'null' incomplete_documents_phone_option: type: - string - 'null' cancellations_enabled: type: - boolean - 'null' cancellations_email_option: type: - string - 'null' cancellations_phone_option: 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). 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.