> ## Documentation Index
> Fetch the complete documentation index at: https://developer.vetcove.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an appointment

> Creates a new appointment for a clinic patient. The appointment is created with an initial status of `CLIENT_REQUESTED`.

An **appointment** represents a scheduled visit for a clinic patient at a clinic, tracking its lifecycle from request through completion or cancellation.



## OpenAPI

````yaml post /ext/v2/appointments/
openapi: 3.1.0
info:
  description: ''
  title: NinjaAPI
  version: 2.0.0
servers:
  - url: https://connect.vetcove.com/
security: []
paths:
  /ext/v2/appointments/:
    post:
      tags:
        - Scheduler
      summary: Create an appointment
      description: >-
        Creates a new appointment for a clinic patient. The appointment is
        created with an initial status of `CLIENT_REQUESTED`.


        An **appointment** represents a scheduled visit for a clinic patient at
        a clinic, tracking its lifecycle from request through completion or
        cancellation.
      operationId: appointments_create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppointmentCreateSchema'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalAppointmentSchema'
          description: Created
      security:
        - ExternalAPIAuth: []
components:
  schemas:
    AppointmentCreateSchema:
      description: Schema for the AppointmentCreateExternalAPIController request body
      properties:
        calendar_id:
          description: The ID of the calendar this appointment belongs to.
          title: Calendar Id
          type: integer
        client_id:
          description: The ID of the clinic client responsible for the appointment.
          title: Client Id
          type: integer
        end_datetime:
          description: ISO 8601 formatted datetime for when the appointment ends.
          format: date-time
          title: End Datetime
          type: string
        kind_id:
          description: The ID of the appointment kind (type of appointment).
          title: Kind Id
          type: integer
        patient_id:
          description: The ID of the clinic patient this appointment is for.
          title: Patient Id
          type: integer
        reason:
          default: ''
          description: The reason for this appointment.
          title: Reason
          type: string
        resource_id:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            The ID of the calendar resource (provider/room) assigned to handle
            this appointment.
          title: Resource Id
        start_datetime:
          description: ISO 8601 formatted datetime for when the appointment starts.
          format: date-time
          title: Start Datetime
          type: string
      required:
        - calendar_id
        - kind_id
        - patient_id
        - client_id
        - start_datetime
        - end_datetime
      title: AppointmentCreateSchema
      type: object
    ExternalAppointmentSchema:
      description: >-
        Appointments represent scheduled visits for patients at a clinic. Each
        appointment is uniquely associated with a patient and can include
        details about the visit, such as the reason for the appointment,
        duration, and any special instructions. If a client has scheduled two
        patients, this will be represented as two separate appointments in our
        system.


        Unlike select legacy PIMS systems that create additional appointments
        for pickup and dropoff events, our appointment object includes both
        pickup and dropoff times when applicable, streamlining the scheduling
        process. This means a surgery would be represented as a single
        appointment with both check-in and check-out times, rather than as
        multiple separate appointments.
      properties:
        alert_tags:
          description: Array of alert tags associated with this appointment.
          items:
            anyOf:
              - $ref: '#/components/schemas/AppointmentAlertTag'
              - const: ''
                type: string
          title: Alert Tags
          type: array
        calendar_id:
          description: The ID of the calendar this appointment belongs to.
          title: Calendar Id
          type: integer
        cancelation_reason:
          anyOf:
            - $ref: '#/components/schemas/AppointmentCancelationReason'
            - const: ''
              type: string
          description: The reason for cancelation or no-show, if applicable.
          title: Cancelation Reason
        cancelation_reason_other:
          anyOf:
            - type: string
            - type: 'null'
          description: Free-text explanation of the cancelation, if one was provided.
          title: Cancelation Reason Other
        clinic_client_id:
          anyOf:
            - type: integer
            - type: 'null'
          description: The ID of the clinic client responsible for the appointment.
          title: Clinic Client Id
        clinic_id:
          description: The ID of the clinic this appointment belongs to.
          title: Clinic Id
          type: integer
        clinic_notes:
          anyOf:
            - {}
            - type: 'null'
          description: JSON structured notes for clinic use.
          title: Clinic Notes
        clinic_patient_id:
          anyOf:
            - type: integer
            - type: 'null'
          description: The ID of the clinic patient this appointment is for.
          title: Clinic Patient Id
        created:
          description: The datetime this object was created.
          format: date-time
          title: Created
          type: string
        deleted:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: The datetime this record was soft deleted.
          title: Deleted
        dropoff_start_datetime:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: >-
            ISO 8601 formatted datetime for when the patient should be dropped
            off.
          title: Dropoff Start Datetime
        end_datetime:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: ISO 8601 formatted datetime for when the appointment ends.
          title: End Datetime
        followup_appointment_ids:
          default: []
          description: List of followup appointment IDs associated with this appointment.
          items:
            type: integer
          title: Followup Appointment Ids
          type: array
        id:
          description: The unique identifier for the appointment.
          title: Id
          type: integer
        is_deleted:
          description: Whether this record is soft deleted or not.
          title: Is Deleted
          type: boolean
        kind:
          anyOf:
            - type: string
            - type: 'null'
          description: The appointment kind (type of appointment).
          title: Kind
        kind_id:
          anyOf:
            - type: integer
            - type: 'null'
          description: The ID of the appointment kind (type of appointment).
          title: Kind Id
        medical_record_id:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            The ID of the medical record associated with this appointment, if
            any.
          title: Medical Record Id
        modified:
          description: >-
            The datetime this object was last modified; changes to related
            entities will not update this field.
          format: date-time
          title: Modified
          type: string
        pickup_start_datetime:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: >-
            ISO 8601 formatted datetime for when the patient should be picked
            up.
          title: Pickup Start Datetime
        reason:
          anyOf:
            - type: string
            - type: 'null'
          description: The reason for this appointment.
          title: Reason
        resource_id:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            The ID of the calendar resource (provider/room) assigned to handle
            this appointment.
          title: Resource Id
        resource_name:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The name of the calendar resource (provider/room) assigned to handle
            this appointment.
          title: Resource Name
        room_id:
          anyOf:
            - type: integer
            - type: 'null'
          description: The ID of the room assigned to this appointment, if any.
          title: Room Id
        room_name:
          anyOf:
            - type: string
            - type: 'null'
          description: The name of the room assigned to this appointment, if any.
          title: Room Name
        start_datetime:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: ISO 8601 formatted datetime for when the appointment starts.
          title: Start Datetime
        status:
          $ref: '#/components/schemas/AppointmentStatus'
          description: The current status of the appointment.
      required:
        - created
        - modified
        - is_deleted
        - deleted
        - id
        - clinic_id
        - calendar_id
        - resource_id
        - room_id
        - clinic_patient_id
        - clinic_client_id
        - start_datetime
        - end_datetime
        - status
        - clinic_notes
        - reason
        - dropoff_start_datetime
        - pickup_start_datetime
        - alert_tags
        - cancelation_reason
        - cancelation_reason_other
      title: Appointment
      type: object
    AppointmentAlertTag:
      enum:
        - CONTAGIOUS
      title: AppointmentAlertTag
      type: string
    AppointmentCancelationReason:
      enum:
        - PATIENT_SEEN_ELSEWHERE
        - CONCERN_RESOLVED
        - PENDING_RESCHEDULE
        - NO_LONGER_NEEDED
        - WILL_RESCHEDULE
        - DOCTOR_UNAVAILABLE
        - CLINIC_SCHEDULE_CHANGE
        - CREATED_IN_ERROR
        - DUPLICATE
        - WRONG_PATIENT
        - WRONG_DATE_OR_TIME
        - UNKNOWN
        - OTHER
        - NO_SHOW
      title: AppointmentCancelationReason
      type: string
    AppointmentStatus:
      enum:
        - CREATING
        - CLIENT_CREATING
        - UNSCHEDULED
        - UNCONFIRMED
        - CONFIRMED
        - DROPPED_OFF
        - CHECKED_IN
        - IN_PROGRESS
        - READY_TO_GO
        - COMPLETED
        - NO_SHOW
        - CANCELED
        - IMPORTED
        - CLIENT_REQUESTED
      title: AppointmentStatus
      type: string
  securitySchemes:
    ExternalAPIAuth:
      scheme: bearer
      type: http

````