Create an appointment for a course

Creates an appointment attached to the course in the path. The path id is the course entity ID. The request body still requires courseIds, but only the path course is attached — pass that course’s layerId in courseIds for consistency. Requires Idempotency-Key. Creator is recorded as an institution admin/moderator.

POST/courses/{id}/appointments

Path parameters

idstringrequired

Course entity ID (`id` from `GET /courses`).

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

404Not Found

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/courses/string/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"
}'

const response = await fetch("https://fuxam.app/api/v4/courses/string/appointments", {
  method: "POST",
  headers: {
    "Idempotency-Key": "string",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "title": "Introduction lecture",
  "dateTime": "2026-09-15T10:00:00.000Z",
  "duration": 90,
  "courseIds": [
    "layer_abc123"
  ],
  "organizerIds": [
    "user_organizer1"
  ],
  "notes": "First session of the semester"
})
});

import requests

response = requests.post(
    "https://fuxam.app/api/v4/courses/string/appointments",
    headers={
        "Idempotency-Key": "string",
        "Content-Type": "application/json"
    },
    json={
  "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"
  }
}

{
  "type": "error",
  "code": "resource_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Course not found",
  "instance": "req_1234567890_abc",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "error",
  "code": "resource_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Course not found",
  "instance": "req_1234567890_abc",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "error",
  "code": "resource_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Course not found",
  "instance": "req_1234567890_abc",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "error",
  "code": "resource_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Course not found",
  "instance": "req_1234567890_abc",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "error",
  "code": "resource_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Course not found",
  "instance": "req_1234567890_abc",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "error",
  "code": "resource_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Course not found",
  "instance": "req_1234567890_abc",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "error",
  "code": "resource_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Course not found",
  "instance": "req_1234567890_abc",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}