# Reserve Appointment

After a time is identified using Available Appointment, it may be temporarily reserved for 15 minutes. 

This is intended for workflows where additional information must be collected before completing the booking, such as capturing patient details to create a new client record. 

Use Finalise Appointment to complete the booking.

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

## Request fields (application/json):

  - `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.

  - `column_number` (integer)

  - `width` (integer)

  - `resource_ids` (array)
    Example: [1,2]

## Response 201 fields (application/json):

  - `appointment_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.

  - `column_number` (integer)

  - `width` (integer)

  - `category` (string)
    Example: Reserved

## 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: 422

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

  - `error.detail` (string)
    Human readable explanation of the error
    Example: There are some issues with the request body.

  - `error.validation` (array)
    List of validation errors for specific fields

  - `error.validation.field` (string)
    Example: surname

  - `error.validation.message` (string)
    Example: The surname field is required.

  - `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