Book Appointment

Creates a new service appointment. The customer must first be created or found via the Customers API.

Request

POST /api/oauth/v2/resource/appointments/service

Header

Header	Value
Authorization	Bearer {access_token}
Content-Type	application/json

Required scope: appointments

Request body

{
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "locationId": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
  "serviceId": "c3d4e5f6-a7b8-9012-cdef-012345678901",
  "customerId": "e5f6a7b8-c9d0-1234-efab-234567890123",
  "status": "active",
  "start": "2026-04-02T09:00:00+02:00",
  "notes": "Bitte nüchtern erscheinen"
}

Request fields

Field	Type	Required	Description
userId	string (UUID)	Yes	ID of the user performing the booking
locationId	string (UUID)	Yes	ID of the location
serviceId	string (UUID)	Yes	ID of the service
customerId	string (UUID)	Yes	ID of the customer
status	string	No	Appointment status: active (default) or request (appointment request)
start	string (ISO 8601)	Yes	Desired appointment start time
notes	string	No	Internal note for the appointment
availabilityCheck	string	No	Availability check: full (full including opening hours), overlap (default, only double bookings), none (no check)

Response

Success (201 Created)

{
  "data": {
    "id": "d4e5f6a7-b8c9-0123-defa-123456789012",
    "title": "Erstordination – Anna Muster",
    "start": "2026-04-02T09:00:00+02:00",
    "end": "2026-04-02T10:00:00+02:00",
    "allDay": false,
    "status": "active",
    "type": "customer",
    "note": "Bitte nüchtern erscheinen",
    "customer": {
      "id": "e5f6a7b8-c9d0-1234-efab-234567890123",
      "firstName": "Anna",
      "lastName": "Muster"
    },
    "service": {
      "id": "c3d4e5f6-a7b8-9012-cdef-012345678901",
      "name": "Erstordination"
    },
    "course": null,
    "source": "oauth",
    "createdAt": "2026-04-01T14:23:00+02:00",
    "updatedAt": "2026-04-01T14:23:00+02:00"
  }
}

Response fields

Field	Type	Description
data.id	string (UUID)	Unique appointment ID
data.title	string	Appointment title
data.start	string (ISO 8601)	Actual start time
data.end	string (ISO 8601)	Actual end time
data.allDay	boolean	All-day appointment
data.status	string	Appointment status (active or request)
data.type	string	Appointment type (e.g. customer)
data.note	string | null	Internal note for the appointment
data.customer	object | null	Linked customer
data.customer.id	string (UUID)	Customer ID
data.customer.firstName	string	First name
data.customer.lastName	string	Last name
data.service	object | null	Booked service
data.service.id	string (UUID)	Service ID
data.service.name	string	Name of the service
data.course	object | null	Linked course (if appointment is a course appointment)
data.source	string	Booking source (e.g. oauth)
data.createdAt	string (ISO 8601)	Creation time
data.updatedAt	string (ISO 8601)	Last modification time

Beispiele

bash

curl -X POST "https://my.offisy.at/api/oauth/v2/resource/appointments/service" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
    "locationId": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
    "serviceId": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
    "customerId": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
    "start": "beispiel",
    "notes": "Terminnotiz",
    "status": "beispiel",
    "availabilityCheck": "beispiel"
  }'

Server

Client-ID

Client-Secret

Parameter

userId *string

locationId *string

serviceId *string

customerId *string

start *string

notes string

status string

availabilityCheck string

Zuerst Token anfordern

Possible errors

Status	Code	Description
400	validation_error	Required fields missing or UUID is invalid
401	invalid_client	Invalid or missing access token
403	insufficient_scope	Scope appointments not present
404	not_found	User, location, service, or customer not found
409	conflict	The selected time slot is no longer available
422	unprocessable_entity	start is in the past
422	booking_error	General booking error (e.g. configuration problem)