---
title: "Create a new appointment with schedule item"
method: POST
path: "/Appointments"
tags: ["Appointments"]
---

# Create a new appointment with schedule item

`POST /Appointments`

## Request body

- CreateAppointmentRequest — Request to create a new appointment (includes schedule item)
  - `clientId` string, required
  - `patientId` string, nullable — Patient under care. Required for normal patient-scoped appointments; must be null for group-visit appointment types (those provide string? CreateAppointmentRequest.PatientGroupId instead). The service-layer validates based on the chosen AppointmentType's IsGroupVisit flag.
  - `patientGroupId` string, nullable — Patient group under care for litter / herd appointment types. Mutually exclusive with string? CreateAppointmentRequest.PatientId; the appointments_subject_chk CHECK constraint enforces exactly-one at the DB level.
  - `reasonForVisit` string, required
  - `notes` string, nullable
  - `customAttributes` string, nullable
  - `appointmentTypeId` string, nullable — The type of appointment (e.g., Wellness Exam, Dental Cleaning).
  - `title` string, required
  - `startTime` string, date-time, required
  - `endTime` string, date-time, required
  - `description` string, nullable
  - `type` string, required
  - `locationId` string, required
  - `assignedToId` string, nullable
  - `scheduleCustomAttributes` string, nullable
  - `isTravelAppointment` boolean
  - `travelDestinationAddress` string, nullable
  - `travelDestinationPlaceId` string, nullable
  - `travelStartingAddress` string, nullable
  - `travelStartingPlaceId` string, nullable
  - `travelDistanceMeters` union
    - integer
    - string, int32
  - `travelDurationMinutes` union
    - integer
    - string, int32
  - `travelIsRoundTrip` boolean, nullable
  - `travelFeeAmount` union
    - number, double
    - string, double
  - `travelAccessNotes` string, nullable

## Response `200`

OK

- AppointmentResponseDto — Full appointment response with all related data
  - `id` string
  - `scheduleItemId` string
  - `scheduleItem` ScheduleItemDto — Schedule item DTO (embedded in appointments)
    - `id` string
    - `title` string
    - `startTime` string, date-time
    - `endTime` string, date-time
    - `description` string, nullable
    - `type` string
    - `locationId` string, nullable
    - `location` LocationSummaryDto
      - `id` string
      - `name` string
      - `isActive` boolean
      - `isVehicle` boolean
      - `isPersonalVehicle` boolean
    - `assignedToId` string, nullable
    - `assignedTo` UserSummaryDto
      - `id` string
      - `email` string
      - `firstName` string, nullable
      - `lastName` string, nullable
      - `displayName` string, nullable
      - `type` string
      - `roleId` string, nullable
      - `roleName` string, nullable
    - `customAttributes` string, nullable
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
  - `clientId` string
  - `client` ClientSummaryDto
    - `id` string
    - `firstName` string
    - `lastName` string
    - `email` string, nullable
    - `phoneNumber` string, nullable
  - `patientId` string, nullable — Set on patient-scoped appointments. Null on group visits — see string? AppointmentResponseDto.PatientGroupId.
  - `patient` PatientSummaryDto — Lightweight patient summary for lists and references
    - `id` string — Unique patient identifier
    - `name` string — The patient's name
    - `species` string — The species name. References a species from GET /species endpoint.
    - `speciesId` string, nullable — The species ID for programmatic lookups.
    - `breed` string — The breed name
    - `sex` string — The patient's sex
    - `dateOfBirth` string, date-time, nullable — Date of birth, if known
    - `isEstimatedAge` boolean
    - `fixed` boolean — Whether the patient is spayed/neutered
    - `treatmentAcceptanceRate` union
      - number, double
      - string, double
  - `patientGroupId` string, nullable — Set on group-visit appointment types (litter / herd). Mutually exclusive with string? AppointmentResponseDto.PatientId.
  - `patientGroup` AppointmentPatientGroupSummaryDto — Lightweight group summary for embedding in appointment responses.
    - `id` string
    - `name` string
    - `groupType` string — "Litter" or "Herd".
    - `speciesName` string, nullable
    - `headCount` union
      - integer
      - string, int32
    - `memberCount` union
      - integer
      - string, int32
  - `reasonForVisit` string
  - `notes` string, nullable
  - `status` string
  - `customAttributes` string, nullable
  - `recordingId` string, nullable
  - `createdAt` string, date-time
  - `updatedAt` string, date-time
  - `isTravelAppointment` boolean
  - `travelDestinationAddress` string, nullable
  - `travelDestinationPlaceId` string, nullable
  - `travelStartingAddress` string, nullable
  - `travelStartingPlaceId` string, nullable
  - `travelDistanceMeters` union
    - integer
    - string, int32
  - `travelDurationMinutes` union
    - integer
    - string, int32
  - `travelIsRoundTrip` boolean, nullable
  - `travelFeeAmount` union
    - number, double
    - string, double
  - `travelAccessNotes` string, nullable
  - `appointmentTypeId` string, nullable
  - `requiresSurgeryRoom` boolean — Whether this appointment type requires a surgery room.
  - `isEmergencySurgeryConversion` boolean — Whether this appointment was converted from a regular exam to emergency surgery.
  - `appointmentTypeDefaultFlowId` string, nullable — Chronicle workflow id sourced from this appointment's <see cref="!:AppointmentType" />. Null falls back to `appointment-default` at the chronicle. Denormalized at read time so the chronicle doesn't need a second appointment-type lookup.
  - `appointmentTypeExamTemplateId` string, nullable — Exam template id sourced from this appointment's <see cref="!:AppointmentType" /> (PAW-741). Resolution at the chronicle exam step: this value, else the provider's personal default, else the standard 7-system view. Denormalized at read time so the chronicle doesn't need a second appointment-type lookup.
  - `appointmentTypeAutoGenerateSoap` boolean — Auto-start SOAP generation when the treatment plan is converted to an invoice (PAW-675). Denormalized from the appointment type; true when the appointment has no type (the platform default is on).
  - `appointmentTypeAutoGenerateDischarge` boolean — Auto-start discharge generation when the SOAP note is approved (PAW-675). Denormalized from the appointment type; true when the appointment has no type (the platform default is on).

---

[API](https://skmtc.net/clinicos/apis/pawthosx-business-api-v1.md) · [All operations](https://skmtc.net/clinicos/apis/pawthosx-business-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clinicos/pawthosx-business-api-v1/revisions/a905bde4e796/schema)