Saltar al contenido
Docs
Español
EnglishDeutschSin traducirEspañolSin traducir
Esc
↑↓navigate↵open⌘Jpreview

Create an appointment

Creates an appointment attached to one or more courses via courseIds (layer IDs from GET /courses). Supports multiple courses in one request. Requires Idempotency-Key. Creator is recorded as an institution admin/moderator.

POST/appointments
Header parameters
Idempotency-Keystringrequired
Unique key to ensure idempotent creation
Request body
requiredapplication/json
titlestringrequired
min length 1 · max length 255
dateTimestring<date-time>required
Start time in ISO 8601. Must include a timezone offset (`Z` or `±HH:MM`).
durationintegerrequired
Duration in minutes
min 1
isOnlineboolean
Hint for online-only format. The server may recompute this from rooms, address, and onlineAddress.
default: false
isHybridboolean
Hint for hybrid format. The server may recompute this from rooms, address, and onlineAddress.
default: false
addressstring
Physical address. May be taken from the first booked room's location.
onlineAddressstring
Online meeting URL (e.g. video link).
locationstring
Free-text location label.
roomsAppointmentRoomInput[]
v4 only — legacy `roomId` / `roomIds` fields are not accepted.
Show properties
Array of AppointmentRoomInput
roomIdstringrequired
Institution room ID from Room Management.
setupIdstring | null
Optional room setup/version ID. Omit or pass null for the default setup.
courseIdsstring[]required
Layer IDs of courses to attach (`layerId` from `GET /courses`, **not** the course entity `id`). Required on all create requests.
min items 1
organizerIdsstring[]
User IDs of organizers (must belong to the institution).
userIdsstring[]
Additional participant user IDs (must belong to the institution).
userGroupIdsstring[]
User group IDs to invite as participants.
appointmentTypeIdstring | null
Institution appointment type ID. There is no public list endpoint — obtain IDs from your institution configuration in the dashboard.
notesstring
Responses
201Appointment created
dataAppointmentrequired
Full appointment from `GET /appointments`, `GET /appointments/{id}`, and create responses. Includes participants, creator, groups, and series when loaded.
Show properties
idstringrequired
titlestringrequired
notesstring
dateTimestring<date-time>required
durationintegerrequired
Duration in minutes
isOnlinebooleanrequired
isHybridbooleanrequired
onlineAddressstring
addressstring
locationstring | null
providerstring
roomIdstring | null
Deprecated — use appointmentRooms.
appointmentRoomsAppointmentRoomBooking[]
Show properties
Array of AppointmentRoomBooking
roomIdstring
setupIdstring | null
roomobject
setupobject | null
appointmentLayersAppointmentLayer[]
Show properties
Array of AppointmentLayer
layerIdstring
layerobject | null
Show properties
idstring
namestring
courseobject | null
Show properties
idstring
Course entity ID
codestring | null
namestring
organizerUsersAppointmentOrganizer[]
Show properties
Array of AppointmentOrganizer
organizerIdstringrequired
appointmentUsersAppointmentUserParticipant[]
Show properties
Array of AppointmentUserParticipant
userIdstring
userAppointmentSafeUser
Show properties
idstring
namestring
emailstring
firstNamestring | null
lastNamestring | null
imagestring | null
appointmentCreatorobject[]
Institution admin/moderator used as creator for API-created appointments.
Show properties
Array of object
userIdstring
userAppointmentSafeUser
Show properties
idstring
namestring
emailstring
firstNamestring | null
lastNamestring | null
imagestring | null
appointmentUserGroupsobject[]
Show properties
Array of object
userGroupIdstring
userGroupobject
appointmentTypeobject | null
seriesobject | null
metaResponseMetarequired
Show properties
requestIdstringrequired
timestampstring<date-time>required
versionstringrequired
Allowed:v4
400Bad Request
typestringrequired
Allowed:error
codestringrequired
Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedrate_limit_exceededinternal_error
titlestringrequired
statusintegerrequired
detailstringrequired
instancestring
errorsobject[]
Show properties
Array of object
fieldstring
messagestring
401Unauthorized
typestringrequired
Allowed:error
codestringrequired
Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedrate_limit_exceededinternal_error
titlestringrequired
statusintegerrequired
detailstringrequired
instancestring
errorsobject[]
Show properties
Array of object
fieldstring
messagestring
403Forbidden
typestringrequired
Allowed:error
codestringrequired
Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedrate_limit_exceededinternal_error
titlestringrequired
statusintegerrequired
detailstringrequired
instancestring
errorsobject[]
Show properties
Array of object
fieldstring
messagestring
409Conflict
typestringrequired
Allowed:error
codestringrequired
Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedrate_limit_exceededinternal_error
titlestringrequired
statusintegerrequired
detailstringrequired
instancestring
errorsobject[]
Show properties
Array of object
fieldstring
messagestring
429Too Many Requests
typestringrequired
Allowed:error
codestringrequired
Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedrate_limit_exceededinternal_error
titlestringrequired
statusintegerrequired
detailstringrequired
instancestring
errorsobject[]
Show properties
Array of object
fieldstring
messagestring
500Internal Server Error
typestringrequired
Allowed:error
codestringrequired
Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedrate_limit_exceededinternal_error
titlestringrequired
statusintegerrequired
detailstringrequired
instancestring
errorsobject[]
Show properties
Array of object
fieldstring
messagestring
Request
curl -X POST "https://fuxam.app/api/v4/appointments" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Introduction lecture",
  "dateTime": "2026-09-15T10:00:00.000Z",
  "duration": 90,
  "courseIds": [
    "layer_abc123"
  ],
  "organizerIds": [
    "user_organizer1"
  ],
  "notes": "First session of the semester"
}'
Response
{
  "data": {
    "id": "appt_def456",
    "title": "Introduction lecture",
    "notes": "First session of the semester",
    "dateTime": "2026-09-15T10:00:00.000Z",
    "duration": 90,
    "isOnline": false,
    "isHybrid": false,
    "onlineAddress": "",
    "address": "Building A, Room 101",
    "location": null,
    "provider": "fuxam",
    "roomId": null,
    "appointmentLayers": [
      {
        "layerId": "layer_abc123",
        "layer": {
          "id": "layer_abc123",
          "name": "CS101"
        },
        "course": {
          "id": "clx1234567890",
          "code": "CS101",
          "name": "Introduction to Computer Science"
        }
      }
    ],
    "appointmentRooms": [],
    "organizerUsers": [
      {
        "organizerId": "user_organizer1"
      }
    ],
    "appointmentUsers": [
      {
        "userId": "user_student1",
        "user": {
          "id": "user_student1",
          "name": "Jane Doe",
          "email": "jane@example.com",
          "firstName": "Jane",
          "lastName": "Doe",
          "image": null
        }
      }
    ],
    "appointmentCreator": [
      {
        "userId": "user_admin1",
        "user": {
          "id": "user_admin1",
          "name": "Admin User",
          "email": "admin@example.com",
          "firstName": "Admin",
          "lastName": "User",
          "image": null
        }
      }
    ],
    "appointmentUserGroups": [],
    "appointmentType": null,
    "series": null
  },
  "meta": {
    "requestId": "req_1234567890_abc",
    "timestamp": "2026-06-02T07:00:00.000Z",
    "version": "v4"
  }
}