Saltar al contenido
Esc
↑↓navegar↵abrir⌘Jvista previa

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
Examples
{
  "title": "Introduction lecture",
  "dateTime": "2026-09-15T10:00:00.000Z",
  "duration": 90,
  "courseIds": [
    "layer_abc123"
  ],
  "notes": "First session of the semester"
}
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
watermarkstring<date-time>

Present on GET /users?updatedSince= pages. Taken at the first page minus a 60s overlap. Bound into pagination.next_cursor. Use it as the next updatedSince after deduping by user id. Delivery is inclusive >= and at-least-once.

400

Bad Request

typestringrequired
Allowed:error
codestringrequired
Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_error
titlestringrequired
statusintegerrequired
detailstringrequired
instancestring
errorsobject[]
Show properties
Array of object
fieldstring
messagestring
existingUserIdstring

Present on 409 email or membership-code conflicts. The user id that already holds the email or code.

activeSessionobject

Present on time-tracking start 409 when a session is already running. Stop this session, then retry start.

Show properties
idstringrequired
startTimestring<date-time>required
conflictingLogobject

Present on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.

Show properties
idstringrequired
startTimestring<date-time>required
endTimestring<date-time> | nullrequired
401

Unauthorized

typestringrequired
Allowed:error
codestringrequired
Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_error
titlestringrequired
statusintegerrequired
detailstringrequired
instancestring
errorsobject[]
Show properties
Array of object
fieldstring
messagestring
existingUserIdstring

Present on 409 email or membership-code conflicts. The user id that already holds the email or code.

activeSessionobject

Present on time-tracking start 409 when a session is already running. Stop this session, then retry start.

Show properties
idstringrequired
startTimestring<date-time>required
conflictingLogobject

Present on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.

Show properties
idstringrequired
startTimestring<date-time>required
endTimestring<date-time> | nullrequired
403

Forbidden

typestringrequired
Allowed:error
codestringrequired
Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_error
titlestringrequired
statusintegerrequired
detailstringrequired
instancestring
errorsobject[]
Show properties
Array of object
fieldstring
messagestring
existingUserIdstring

Present on 409 email or membership-code conflicts. The user id that already holds the email or code.

activeSessionobject

Present on time-tracking start 409 when a session is already running. Stop this session, then retry start.

Show properties
idstringrequired
startTimestring<date-time>required
conflictingLogobject

Present on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.

Show properties
idstringrequired
startTimestring<date-time>required
endTimestring<date-time> | nullrequired
409

Conflict — duplicate email or membership code (body includes existingUserId when known), a time-tracking session that is already running (activeSession), a time-tracking interval that overlaps an existing log (conflictingLog), idempotency key reused with a different body (idempotency_key_reused), or concurrent request with the same key still in progress (idempotency_key_in_progress)

typestringrequired
Allowed:error
codestringrequired
Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_error
titlestringrequired
statusintegerrequired
detailstringrequired
instancestring
errorsobject[]
Show properties
Array of object
fieldstring
messagestring
existingUserIdstring

Present on 409 email or membership-code conflicts. The user id that already holds the email or code.

activeSessionobject

Present on time-tracking start 409 when a session is already running. Stop this session, then retry start.

Show properties
idstringrequired
startTimestring<date-time>required
conflictingLogobject

Present on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.

Show properties
idstringrequired
startTimestring<date-time>required
endTimestring<date-time> | nullrequired
429

Too Many Requests — 1000 requests per minute per institution. Includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (ISO-8601), and Retry-After (seconds).

typestringrequired
Allowed:error
codestringrequired
Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_error
titlestringrequired
statusintegerrequired
detailstringrequired
instancestring
errorsobject[]
Show properties
Array of object
fieldstring
messagestring
existingUserIdstring

Present on 409 email or membership-code conflicts. The user id that already holds the email or code.

activeSessionobject

Present on time-tracking start 409 when a session is already running. Stop this session, then retry start.

Show properties
idstringrequired
startTimestring<date-time>required
conflictingLogobject

Present on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.

Show properties
idstringrequired
startTimestring<date-time>required
endTimestring<date-time> | nullrequired
500

Internal Server Error

typestringrequired
Allowed:error
codestringrequired
Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_error
titlestringrequired
statusintegerrequired
detailstringrequired
instancestring
errorsobject[]
Show properties
Array of object
fieldstring
messagestring
existingUserIdstring

Present on 409 email or membership-code conflicts. The user id that already holds the email or code.

activeSessionobject

Present on time-tracking start 409 when a session is already running. Stop this session, then retry start.

Show properties
idstringrequired
startTimestring<date-time>required
conflictingLogobject

Present on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.

Show properties
idstringrequired
startTimestring<date-time>required
endTimestring<date-time> | nullrequired
Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST 'https://fuxam.app/api/v4/appointments' \
  -H 'Authorization: Basic YOUR_CREDENTIALS' \
  -H 'Idempotency-Key: string' \
  -H 'Accept: application/json' \
  -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"
}'
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"
  }
}

¿Te ha resultado útil esta página?