> ## Documentation Index > Fetch the complete documentation index at: https://docs.usecobalt.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Appointments > Gets a list of appointments. ## OpenAPI ````yaml GET /appointments openapi: 3.0.0 info: title: Cobalt API version: 1.0.1 description: API for interacting with Cobalt's EHR integration services servers: - url: https://api.usecobalt.com/v1 security: - ClientCredentials: [] ClientSecret: [] AccessToken: [] paths: /appointments: get: summary: Get Appointments parameters: - in: query name: start_date required: false schema: type: string format: date description: >- The start of the date range (ISO 8601 format). Required unless emr_appointment_id is provided. - in: query name: end_date required: false schema: type: string format: date description: >- The end of the date range (ISO 8601 format). Required unless emr_appointment_id is provided. - in: query name: patient_mrn schema: type: string description: The mrn of the patient to filter appointments by - in: query name: patient_name schema: type: string description: >- The name of the patient to filter appointments by (case-insensitive, partial match) - in: query name: patient_phone schema: type: string description: The phone number of the patient to filter appointments by - in: query name: status schema: type: string description: Only include appointments with the given status - in: query name: include_note schema: type: string enum: - 'true' - 'false' description: Indicate whether progress notes should be included when available - in: query name: include_schedule_blocks schema: type: string enum: - 'true' - 'false' description: >- Indicate whether schedule blocks (eg. Lunch Break) should be included - in: query name: appointment_mode schema: type: string enum: - office - telemedicine description: Filter by office or telemedicine appointments - in: query name: provider_ehr_id schema: type: string description: Filter appointments by provider EHR ID - in: query name: location_ehr_id schema: type: string description: Filter appointments by location EHR ID - in: query name: appointment_type schema: type: string description: >- Filter appointments by appointment type (e.g., "New Patient", "Follow Up", "Annual Checkup") - in: query name: secondary_provider_ehr_id schema: type: string description: Filter appointments by secondary provider EHR ID - in: query name: emr_appointment_id schema: type: string description: >- Filter appointments by EMR appointment ID. When provided, start_date and end_date are not required and the matching appointment is returned directly. responses: '200': description: Successful response content: application/json: schema: type: object properties: success: type: boolean appointments: type: array items: type: object properties: id: type: string description: Cobalt appointment ID (UUID with hyphens stripped). ehr_appointment_id: type: string description: >- The appointment's identifier in the source EMR. Deprecated alias of emr_appointment_id. emr_appointment_id: type: string description: The appointment's identifier in the source EMR. datetime: type: string format: date-time description: >- Appointment start time as an ISO 8601 timestamp in the user's configured timezone. duration: type: number description: Appointment duration in minutes. status: type: string description: >- Current appointment status (e.g., "scheduled", "checked_in", "completed", "cancelled"). appointment_type: type: string description: >- EHR-defined appointment type (e.g., "New Patient Visit", "Follow-up"). appointment_mode: type: string enum: - office - telemedicine description: Whether the visit is in-office or telemedicine. location: type: string nullable: true description: >- EHR location identifier where the appointment is scheduled. reason: type: string nullable: true description: The appointment booking reason, when available. complaint_type: type: string nullable: true description: >- Chief complaint or visit reason category, when available. patient_name: type: string description: >- Raw patient identifier as stored by the source EHR (often formatted as "Last, First"). For a clean first/last split, use `patient_first_name` and `patient_last_name` instead. patient_first_name: type: string description: >- Patient first name. Omitted from the response when not available. patient_last_name: type: string description: >- Patient last name. Omitted from the response when not available. patient_mrn: type: string description: The patient's Medical Record Number. patient_ehr_id: type: string description: >- The patient's identifier in the source EHR. May equal `patient_mrn` for EHRs that do not distinguish the two. patient_dob: type: string nullable: true description: Patient date of birth (YYYY-MM-DD). patient_gender: type: string nullable: true description: Patient sex/gender as recorded in the EHR. patient_phone: type: string description: >- Patient phone number. Omitted from the response when not available. provider_ehr_id: type: string nullable: true description: Primary provider's identifier in the source EHR. provider_name: type: string nullable: true description: >- Primary provider's display name, resolved from Cobalt's provider directory. provider_npi: type: string description: >- Primary provider's NPI. Omitted from the response when not on file. secondary_provider_ehr_id: type: string nullable: true description: >- Secondary provider's identifier in the source EHR, when applicable. insurance: type: string nullable: true description: Primary insurance plan name. insurance_number: type: string nullable: true description: Primary insurance member/policy number. insurance_group_number: type: string nullable: true description: Primary insurance group number. insurance_subscriber: type: string nullable: true description: Primary insurance subscriber name. secondary_insurance: type: string nullable: true description: Secondary insurance plan name, when present. secondary_insurance_number: type: string nullable: true description: >- Secondary insurance member/policy number, when present. insurances: nullable: true description: >- Structured list of all insurance plans on file for the appointment, when available. oneOf: - type: array items: type: object - type: object diagnoses: nullable: true description: >- Structured diagnosis data captured for the visit, when available. oneOf: - type: array items: type: object - type: object medications: nullable: true description: >- Structured medication data captured for the visit, when available. oneOf: - type: array items: type: object - type: object note: type: string description: >- Appointment note text. Only included when the request is made with `include_note=true`. progress_note: type: string nullable: true description: >- Progress note content for the visit. Only included when the request is made with `include_note=true`. created_at: type: string format: date-time description: >- When the appointment row was first created in Cobalt. object_metadata: type: object description: >- Provenance metadata describing how this appointment record was created. properties: source: type: string enum: - cobalt_operation - ehr_sync - unknown description: >- `cobalt_operation` if Cobalt created the appointment, `ehr_sync` if it was ingested from the EHR, `unknown` otherwise. created_at: type: string format: date-time description: >- When the creating Cobalt operation completed. Only present when `source` is `cobalt_operation`. components: securitySchemes: ClientCredentials: type: apiKey in: header name: client_id ClientSecret: type: apiKey in: header name: client_secret AccessToken: type: apiKey in: header name: access_token ````