Calendar

Create a calendar entry

Creates an appointment owned by the authenticated user inside their company. end_time must be strictly after start_time. The response is the fully materialized entry (denormalized customer / vehicle / calendar / user fields included) so the client can render the new row without a follow-up GET.

Foreign-key references in the body (customer_id, vehicle_id, worksheet_id, work_category_id, calendar_id) must resolve to resources owned by the authenticated user's company. Unreachable refs return 422 parameter_invalid pointing at the offending field.

worksheet_id links the appointment to a scheda lavoro. Omit customer_id / vehicle_id to take them from the worksheet; when sent, they must be the worksheet's (a worksheet without a vehicle fits any vehicle of its customer), otherwise the request returns 422 parameter_invalid on /worksheet_id. Sending worksheet_id needs worksheets.read (the key's scope, or the app user's permission); without it the request returns 403.

Request body

titlestring required

descriptionstring nullable

start_timestring date-time required

RFC 3339 timestamp supplied by the client. Must fall between 1900-01-01 and 2100-12-31. A year outside that window is a typo (2025 mistyped as 0025 is the common one), and the app's own date pickers refuse the same range — a record written with one would not be editable in the web UI afterwards. Out of range → 422 parameter_invalid with param pointing at the offending field.

end_timestring date-time required

RFC 3339 timestamp supplied by the client. Must fall between 1900-01-01 and 2100-12-31. A year outside that window is a typo (2025 mistyped as 0025 is the common one), and the app's own date pickers refuse the same range — a record written with one would not be editable in the web UI afterwards. Out of range → 422 parameter_invalid with param pointing at the offending field.

colorstring required

email_reminderboolean

customer_idstring uuid nullable

vehicle_idstring uuid nullable

worksheet_idstring uuid nullable

work_category_idstring uuid nullable

Single-category form, accepted in every revision: the document's only category. To set several, send work_category_ids instead (not both).

work_category_idsstring[]

The document's work categories, in the order chosen (work_category_id in responses reports the first). Trimmed and de-duplicated (first occurrence wins); at most 10, each one of the company's categories (GET /v1/work-categories) — an unknown id is reported on /work_category_ids/{i}. Do not send together with work_category_id: both → 422 parameter_invalid. Available since revision 2026-10-03.

calendar_idstring uuid nullable

auto_reminder_enabledboolean

auto_reminder_channel'email' | 'sms' | 'whatsapp' | 'null' nullable

Response

Calendar entry created.

object'calendar_entry' required

idstring uuid required

titlestring required

descriptionstring nullable

user_idstring uuid required

start_timestring date-time required

end_timestring date-time required

colorstring required

Hex colour, e.g. #2563eb

email_reminderboolean required

customer_idstring uuid nullable

vehicle_idstring uuid nullable

worksheet_idstring uuid nullable

quote_idstring uuid nullable

checkin_idstring uuid nullable

work_category_idstring uuid nullable

work_category_namestring nullable

work_category_idsstring[] required

Every work category ("categoria") of the document, in the order chosen. work_category_id (kept for clients that handle a single category) always equals the first. [] when the document has none, never null. Available since revision 2026-10-03.

calendar_idstring uuid nullable

auto_reminder_enabledboolean required

auto_reminder_channel'email' | 'sms' | 'whatsapp' | 'null' nullable

auto_reminder_sent_atstring date-time nullable

created_atstring date-time required

updated_atstring date-time required

deleted_atstring date-time nullable

Create a calendar entry

Request

Request body

Response

Changes