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

Authorization

AuthorizationBasic auth · headerrequired

Basic Auth with clientId as username and clientSecret as password

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

201

Appointment 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

400

Bad 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

401

Unauthorized

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

403

Forbidden

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

409

Conflict

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

429

Too 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

500

Internal 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

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Basic auth usernameBasic auth password

Remember on this deviceInclude my values in samples

Parameters

Idempotency-Keyheader*Unique key to ensure idempotent creation

Bodyapplication/json

Request body

Request

curl -X POST 'https://fuxam.app/api/v4/appointments' \
  -H 'Authorization: Basic YOUR_CREDENTIALS' \
  -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"
  ],
  "notes": "First session of the semester"
}'

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

import requests

response = requests.post(
    "https://fuxam.app/api/v4/appointments",
    headers={
        "Authorization": "Basic YOUR_CREDENTIALS",
        "Idempotency-Key": "string",
        "Content-Type": "application/json"
    },
    data="{\n  \"title\": \"Introduction lecture\",\n  \"dateTime\": \"2026-09-15T10:00:00.000Z\",\n  \"duration\": 90,\n  \"courseIds\": [\n    \"layer_abc123\"\n  ],\n  \"notes\": \"First session of the semester\"\n}",
)

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": "",
    "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": [],
    "appointmentUsers": [],
    "appointmentCreator": [
      {
        "userId": "user_admin1",
        "user": {
          "id": "user_admin1",
          "name": "Admin User",
          "email": "admin@example.com"
        }
      }
    ],
    "appointmentUserGroups": [],
    "appointmentType": null,
    "series": null
  },
  "meta": {
    "requestId": "req_1782305464335_hqnbhdhoaer",
    "timestamp": "2026-06-24T12:51:04.381Z",
    "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"
    }
  ]
}