Resource type: appointmentList
appointmentList is our new API call, introduced to improve how we retrieve appointments. The appointmentList API is designed to be more focused. It provides only the essential information needed for the list and delivers the confirmation status more directly. This makes the process of fetching appointments for the list more streamlined and uses resources more effectively.
The parameter is divided into two: data and filter
Parameters:
-
dataid
STRING. The ID is the number of RecordID from the Appointment.createdBy
STRING. Refers to the user who initially created the calendar entry. It is an identifier that points to the person responsible for the appointment’s creation.modified
DATETIME. Refers to the timestamp that indicates when a calendar entry was last changed or updated.subject
STRING. The subject is the title or short description of the calendar entry.notes
STRING. Notes are additional details or information related to the calendar entry.type
OBJECT. The appointment type (e.g., meeting, visit), represented by a “value” and a “label”.status
OBJECT. The status is the current state of the calendar entry, also with a “value” and a “label”. Possible values:active,completed,canceled,participantsAvailable.confirmationStatus
STRING. Shows the overall confirmation status of the appointment. Depends on the status of the appointment confirmations of the addresses. Possible values:canceled,confirmed,confirmedandcanceled,not-set,sent.private
BOOLEAN. Indicates whether the calendar entry is marked as private or not.date
OBJECT. Represents the start and end dates and times of the calendar entry.travelTime
OBJECT. Specifies the travel time associated with the appointment. It’s an object with outward and return fields. Can benullif travel time is disabled.location
OBJECT. Describes the location of the appointment (where the appointment takes place).recurrence
OBJECT. Describes how often the appointment repeats. Uses an INT datatype for the interval, and DATE for the start and end.reminder
OBJECT. The reminder is a setting to provide a notification before the appointment begins. Uses INT fortimeBefore, STRING forrecipients, ARRAY(of STRINGS) fortypes, and BOOLEAN forconfirmedOnly.groups
ARRAY. Which groups participate in the appointment. Each group has an ID and name represented as STRING.users
ARRAY. Which users participate in the appointment. ID, userName, firstName, lastName, and email are represented as STRING.resources
ARRAY. Resources associated with the appointment. Each resource has an ID and name represented as STRING.contacts
ARRAY. Contacts associated with the appointment. Each contact has an ID and confirmationStatus represented as STRING.estate
OBJECT. The estate associated with the appointment.project
OBJECT. A project associated with the appointment.conflicts
OBJECT. Returns information on the different overlaps for users, resources, addresses and properties.
filterstartDate
DATE. MANDATORY. Start date of the time interval for the requested appointments. All participants in the appointment are taken into account, but not the appointment creator himself if he is not a participant in the appointment.endDate
DATE. MANDATORY. End date of the time interval for the requested appointments. All participants in the appointment are taken into account, but not the appointment creator himself if he is not a participant in the appointment.isCancelled
BOOLEAN. It’s a boolean filter (true/false) to retrieve calendar entries that are either cancelled or not cancelled.isDone
BOOLEAN. Is a boolean filter (true/false) to retrieve calendar entries based on whether they are marked as “done” (completed) or not.isRecurrent
BOOLEAN. It’s a boolean filter (true/false) to retrieve calendar entries that are either recurring or not.userIds
ARRAY. Filters calendar entries by user. Provide an array of user IDs (as strings) to retrieve entries associated exclusively with those users. The “Required Data Formats” specify that all identifiers, such as user IDs, are to be formatted as<STRING>.groupIds
ARRAY. Similar touserIds, an array of group IDs (strings). WhengroupIdsis included in the filter, the API will only return calendar events associated with the groups whose IDs are listed in this array. As with user IDs, all<ID>data types must be represented as<STRING>according to “Required Data Formats”.notesARRAY. Allows filtering calendar entries based on the content of their “notes” field. The filter value should be an array of objects, where each object specifies an operation and a value. For example:
"notes": [{"op": "!=", "val": "secret"}].op: The operator (e.g.,!=for “not equals” or “does not contain”,=for “equals” or “contains”).val: The value to be checked against the notes content.
Note : There is a required field for single resource queries: resourceId. The following filter parameters: notes, createdBy, type,and subject will support the SQL operators function (e.g., !=, =). Example: "subject": [{"op": "!=", "val": "test"}]. With the parameter filter createdBy and the value von , you can read out all appointments created by a user.
Possible values for op are the following SQL operators:
is or =, >, <, >=, <=, != or <>, between, like, not like, in, not in
For the operator like the value % can be specified as a placeholder.
Request example
{
"actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:get",
"resourceid": "",
"identifier": "",
"resourcetype": "appointmentList",
"parameters": {
"data": [
"id",
"createdBy",
"modified",
"subject",
"notes",
"type",
"status",
"confirmationStatus",
"private",
"date",
"travelTime",
"location",
"recurrence",
"reminder",
"groups",
"users",
"resources",
"contacts",
"estate",
"project"
],
"filter": {
"startDate": "2025-05-22",
"endDate": "2025-05-22",
"isDone": false,
"isCancelled": false,
"notes": [
{
"op": "=",
"val": "test123"
}
]
}
}
}
Response example
{
"status": {
"code": 200,
"errorcode": 0,
"message": "OK"
},
"response": {
"results": [
{
"actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:get",
"resourceid": "",
"resourcetype": "appointmentList",
"cacheable": true,
"identifier": "",
"data": {
"meta": {
"cntabsolute": 1
},
"records": [
{
"id": 7,
"type": "calendar",
"elements": {
"id": "7",
"createdBy": "max",
"modified": "2025-06-04T10:24:14+00:00",
"subject": "Test von Max Mustermann",
"notes": "test123",
"confirmationStatus": "not-set",
"private": false,
"type": {
"value": "Besuch des Kunden im Beratungsbüro",
"label": "Besuch des Kunden im Beratungsbüro"
},
"status": {
"value": "active",
"label": "active"
},
"date": {
"start": "2025-05-22T08:00:00+00:00",
"end": "2025-05-22T08:30:00+00:00",
"allDay": false
},
"travelTime": {
"outward": 30,
"return": 30
},
"location": {
"type": "customer",
"value": "Charlottenburger Allee 5, 52068 Aachen, Deutschland"
},
"recurrence": null,
"reminder": {
"timeBefore": 15,
"recipients": "all",
"confirmedOnly": false,
"types": []
},
"groups": [
{
"id": "219",
"name": "Test_Gruppe"
}
],
"users": [
{
"id": "21",
"userName": "max",
"firstName": "Max",
"lastName": "Mustermann",
"email": "max.mustermann@mytest.de"
},
{
"id": "31",
"userName": "gaby",
"firstName": "Gaby",
"lastName": "Musterfrau",
"email": "musterfrau2@my-test.de"
}
],
"resources": [],
"contacts": [
{
"id": "153",
"confirmationStatus": "not-set"
}
],
"estate": {
"id": "61"
},
"project": {
"id": "1"
}
}
}
]
},
"status": {
"errorcode": 0,
"message": "OK"
}
}
]
}
}