# Appointments

Endpoints from `appointments` routes module.

## List appointments

 - [GET /v1/appointments](https://timify-dev-api.redocly.app/apis/openapi/appointments/getv1appointments.md): List appointments for resources filtered by a time interval or other criteria.

Date Requirements:
- Default: Both from_date AND to_date are REQUIRED - Exception: When filtering by appointment IDs using the ids parameter, date parameters become OPTIONAL - Time Alternative: Can use from_time and to_time as an alternative to date parameters (both must be provided together) - Constraint: Date interval cannot exceed 365 days

Pagination Defaults:
- If page or limit is not provided or is 0, defaults to page=1 and limit=10000 - To override defaults, provide both page > 0 and limit > 0

## Create appointment

 - [POST /v1/appointments](https://timify-dev-api.redocly.app/apis/openapi/appointments/postv1appointments.md): Create a new appointment. Supports single-resource, multi-resource (resourceIds), recurring, group-service (course), and external-id modes.

Field Requirements:
- title is conditionally required: omit it only if all of service_id, external_service_id, duration, and duration_pattern are provided
- service_id and external_service_id are mutually exclusive
- resource_ids and external_resource_ids are mutually exclusive
- When is_course=true the appointment is treated as a group event (course/workshop)
- When recurring is provided, both timezone and frequency fields are required

Datetime Format:
- Use YYYY-MM-DD HH:mm format (e.g., "2026-03-15 14:30")
- Minutes must be divisible by 5 (valid: :00, :05, :10, :15, etc.)

## Bulk delete appointments

 - [POST /v1/appointments/delete/bulk](https://timify-dev-api.redocly.app/apis/openapi/appointments/postv1appointmentsdeletebulk.md): Delete multiple appointments by their IDs in a single request.

Notification Behavior:
- has_notify_customers: Send cancellation notification to all customers attached to the appointments
- has_notify_resources: Send cancellation notification to all assigned resources
- skip_single_emitter: When true, skip notifications for one-off (non-recurring) appointments
- skip_multiple_emitter: When true, skip notifications for recurring appointment series

All notification flags default to false (no notifications sent).

## Import or update appointments

 - [POST /v1/appointments/import/bulk](https://timify-dev-api.redocly.app/apis/openapi/appointments/postv1appointmentsimportbulk.md): Bulk create or update appointments asynchronously. Supports two import modes:

Direct Import (recommended):
- Pass events array directly with appointment objects
- Each object supports all fields from POST /v1/appointments
- Include importEventId for upsert matching (if a record with this ID exists, it will be updated)

URL-based Import:
- Pass url pointing to a file containing events (JSON or custom format)
- Optionally pass secret for authentication
- Useful for large imports from external sources

Upsert Behavior:
- If an appointment with matching importEventId exists, it will be updated
- If an appointment with matching id exists, it will be updated
- Otherwise, a new appointment is created

Notifications:
- has_notify_customers: Send notifications to customers for imported appointments
- has_notify_resources: Send notifications to assigned resources for imported appointments
- skip_emitter: When true, skip all notifications during import
- Default: No notifications sent

## Create appointment with combination service

 - [POST /v1/appointments/multiple](https://timify-dev-api.redocly.app/apis/openapi/appointments/postv1appointmentsmultiple.md): Create a new multi-service appointment combining multiple services in a single booking.

Required Fields:
- service_id: ID of the primary service
- duration: Duration in minutes (must be divisible by 5)
- timezone: IANA timezone identifier (e.g., Europe/Berlin)
- combination_services: Array of service configurations (each must have service_id and duration)

Datetime Format:
Appointments must be created using the format YYYY-MM-DD HH:mm with minutes divisible by 5 (e.g., :00, :05, :10, ..., :55). This is NOT ISO 8601 format—minutes must align to 5-minute intervals.

Conditional Fields:
- max_participants: Required when is_course=true and must be ≥1
- participants: Should be provided when is_course=true

Color Constraint:
Must be one of 16 predefined hex codes: #82a774, #b22e53, #ebb65d, #95c5a6, #b26492, #cc9e52, #8ebec3, #a476ca, #e5774c, #7684ca, #5d5a79, #8b8b8b, #c46f4e, #7b6161, #6882b0, #385f87

Recurring Appointments:
If recurring is provided, it must include:
- timezone: IANA timezone identifier
- frequency: One of DAYS, WEEKS, MONTHS, YEARS

Deep Link Configuration:
Type must be 'PRIVATE' to enable pre-reservation deep link settings.

## Create appointment reservation

 - [POST /v1/appointments/reservation](https://timify-dev-api.redocly.app/apis/openapi/appointments/postv1appointmentsreservation.md): Reserve a time slot for an appointment.

Required Fields:
- date: Appointment date in YYYY-MM-DD format
- minute: Minute of the day (0-1439) when the appointment should start. Must be divisible by 5.

Conditional Requirements:
Either provide service_id OR both title and duration:
- Option 1: Use service_id to reserve a time slot for an existing service
- Option 2: Provide both title and duration to reserve a custom appointment slot

Constraints:
- duration and minute must be divisible by 5 (must align to 5-minute intervals)
- minute range: 0-1439 (corresponds to 00:00-23:55)
- Cannot specify both service_id and custom title+duration

Resource Assignment:
- Optionally assign resources via resource_ids (internal IDs) or external_resource_ids
- These arrays should have at least one item if provided

## Delete appointment

 - [DELETE /v1/appointments/{appointmentId}](https://timify-dev-api.redocly.app/apis/openapi/appointments/deletev1appointmentsbyappointmentid.md): Permanently delete an appointment. Supports externalId lookup via ?external=1. Use has_notify_customers and has_notify_resources to send cancellation notifications.

## Fetch appointment

 - [GET /v1/appointments/{appointmentId}](https://timify-dev-api.redocly.app/apis/openapi/appointments/getv1appointmentsbyappointmentid.md): Fetch a single appointment by its TIMIFY ID or external ID.

## Update appointment

 - [PATCH /v1/appointments/{appointmentId}](https://timify-dev-api.redocly.app/apis/openapi/appointments/patchv1appointmentsbyappointmentid.md): Update an existing appointment with partial updates.

Datetime Format:
Appointments must be updated using the format YYYY-MM-DD HH:mm with minutes divisible by 5 (e.g., :00, :05, :10, ..., :55). This is NOT ISO 8601 format.

Partial Updates:
Only the fields provided in the request body will be changed. Omitted fields remain unchanged.

Duration Constraints:
- duration, duration_before, duration_after: Must be divisible by 5
- reserve_for: Must be divisible by 5

Conditional Requirements:
- max_participants: Minimum 1 when is_course=true

Color Constraint:
Must be one of 16 predefined hex codes: #82a774, #b22e53, #ebb65d, #95c5a6, #b26492, #cc9e52, #8ebec3, #a476ca, #e5774c, #7684ca, #5d5a79, #8b8b8b, #c46f4e, #7b6161, #6882b0, #385f87

External ID Lookup:
Use ?external=1 query parameter to look up the appointment by externalId instead of TIMIFY's internal MongoDB ID.