# Create Appointment

We recommend using Available Appointment to discover available times for a practitioner. After a time is found, use Reserve (optional) and Finalise Appointment to complete the booking process.
Alternatively, you can use Create Appointment, which requires you to pass in start and end times for the appointment.
The API will apply the default Appointment Type configuration for the following, unless specified in the request body:
- Width
- Resource
- Item or Item Group

For practitioner records with multiple active professions, their default profession will be used unless `profession_id` is specified in the body.
Practitioners can have multiple appointment book columns as defined in Practitioner object. Supply the column number to control which column the appointment is booked in. The specified `column_number` must not exceed the number of columns enabled on the practitioner record. Requests that specify an invalid column number will be rejected.

Endpoint: POST /appointment
Version: v1
Security: x-api-key, a-api-key

## Request fields (application/json):

  - `client_id` (integer, required)

  - `appointment_type_id` (integer, required)

  - `app_time` (string, required)
    ISO 8601 local datetime in the tenant's timezone.
    Example: 2026-01-01T12:05:30

  - `practitioner_id` (integer, required)

  - `business_id` (integer, required)

  - `duration` (integer, required)
    Must be between 5 and 1440 and divisible by 5.

  - `appointment_status_id` (integer)
    If omitted, the appointment is created with the system default status of Booked.

  - `account_id` (integer)
    If omitted, the patient's default account is applied.

  - `profession_id` (integer)
    If omitted, the practitioner's default profession is applied.

  - `item_id` (integer)
    If `item_id` is not null, then `item_group_id` must be null
If omitted, the default item configured on the selected appointment type is applied.

  - `item_group_id` (integer)
    If `item_group_id` is not null, then `item_id` must be null
If omitted, the default item group configured on the selected appointment type is applied.

  - `notes` (string)

  - `column_number` (integer)

  - `width` (integer)
    If omitted, the default width configured on the selected appointment type is applied.

  - `resource_ids` (array)
    If omitted, the default resources configured on the selected appointment type are applied.
    Example: [1,2]

  - `sms_reminder` (boolean)
    If omitted, patient default preferences are applied

  - `email_reminder` (boolean)
    If omitted, patient default preferences are applied

  - `sms_confirmation` (boolean)
    If omitted, patient default preferences are applied

  - `email_confirmation` (boolean)
    If omitted, patient default preferences are applied

  - `sms_follow_up` (boolean)
    If omitted, patient default preferences are applied

  - `email_follow_up` (boolean)
    If omitted, patient default preferences are applied

## Response 201 fields (application/json):

  - `row_num` (integer)

  - `total_rows` (integer)

  - `links` (object)

  - `links.self` (string)
    Example: https://api.pracsuite.com/v1/appointment/1

  - `links.resources` (string)
    Example: https://api.pracsuite.com/v1/appointment/1/resource

  - `tenant_id` (integer)

  - `appointment_id` (integer)

  - `client_id` (integer)

  - `app_time` (string)
    ISO 8601 local datetime in the tenant's timezone.
    Example: 2026-01-01T12:05:30

  - `description` (string)

  - `appointment_type_id` (integer)

  - `appointment_status_id` (integer)

  - `category` (string)

  - `duration` (integer)

  - `notes` (string)

  - `practitioner_id` (integer)

  - `business_id` (integer)

  - `profession_id` (integer)

  - `item_id` (integer)

  - `account_id` (integer)

  - `created` (string)
    RFC 3339 UTC date-time (Z) with microsecond precision.
    Example: 2020-09-12T11:09:42.687393Z

  - `modified` (string)
    RFC 3339 UTC date-time (Z) with microsecond precision.
    Example: 2020-09-12T11:09:42.687393Z

  - `item_group_id` (integer)

  - `telehealth_patient_link` (string)

  - `telehealth_practitioner_link` (string)

  - `resource_ids` (array)

## Response 401 fields (application/json):

  - `error` (object, required)

  - `error.status` (integer)
    Example: 403

  - `error.code` (string)
    Example: UNAUTHORIZED

  - `error.detail` (string)
    Human readable explanation of the error
    Example: Access could not be verified for this request.

  - `request_id` (string, required)
    Example: 00000000-0000-0000-0000-000000000000

## Response 403 fields (application/json):

  - `error` (object, required)

  - `error.status` (integer)
    Example: 403

  - `error.code` (string)
    Example: MISSING_AUTHENTICATION_TOKEN

  - `error.detail` (string)
    Human readable explanation of the error
    Example: Authentication token is missing or the requested endpoint does not exist

  - `request_id` (string, required)
    Example: 00000000-0000-0000-0000-000000000000

## Response 409 fields (application/json):

  - `error` (object, required)

  - `error.status` (integer)
    Example: 409

  - `error.code` (string)
    Example: RESERVE_APPOINTMENT_CONFLICT

  - `error.detail` (string)
    Human readable explanation of the error
    Example: This appointment slot is taken.

  - `request_id` (string, required)
    Example: 00000000-0000-0000-0000-000000000000

## Response 422 fields (application/json):

  - `error` (object, required)

  - `error.status` (integer)
    Example: 500

  - `error.code` (string)
    Example: SERVER_ERROR

  - `error.detail` (string)
    Human readable explanation of the error
    Example: An unexpected error occurred while processing your request. Please try again in a few minutes. If it keeps happening, contact support with Request ID: 00000000-0000-0000-0000-000000000000.

  - `request_id` (string, required)
    Example: 00000000-0000-0000-0000-000000000000

## Response 500 fields (application/json):

  - `error` (object, required)

  - `error.status` (integer)
    Example: 500

  - `error.code` (string)
    Example: SERVER_ERROR

  - `error.detail` (string)
    Human readable explanation of the error
    Example: An unexpected error occurred while processing your request. Please try again in a few minutes. If it keeps happening, contact support with Request ID: 00000000-0000-0000-0000-000000000000.

  - `request_id` (string, required)
    Example: 00000000-0000-0000-0000-000000000000