Get Appointments - onOffice API

Resource type: appointmentList

appointmentList is an API resource type for retrieving calendar appointments. It supports two request modes: a list request, which returns multiple appointments matching a filter, and a single-appointment request, which requires a resourceId.

The request is split into two parameters: data, which specifies which fields to return, and filter, which defines the criteria appointments must match (e.g. time range, status, assigned users or groups). Only the requested data fields are included in the response; fields not listed are omitted entirely rather than returned as null.

The response is a map keyed by appointment ID. A single query can return at most 500 appointments; larger time ranges should be split into smaller queries to stay within this limit.

Parameters:

- data
  - id
    STRING. The unique record ID of the appointment.
  - createdBy
    STRING. The user name of the user who initially created the entry.
  - modified
    DATETIME. Timestamp indicating when the entry was last updated.
  - subject
    STRING. The title or short description of the appointment.
  - notes
    STRING. Additional details or description text.
  - type
    OBJECT. The appointment type (e.g., meeting, visit), represented by a “value” and a “label”. Possible values are the values from the administration under “Types of action” in the “appointment” module.
  - status
    OBJECT. Current state of the entry. Possible values: active, completed, canceled, participantsAvailable.
  - confirmationStatus
    STRING. Overall confirmation status. Depends on the status of the appointment confirmations of the addresses. Possible values: canceled, confirmed, confirmed and canceled, not-set, sent.
  - private
    BOOLEAN. Indicates if the entry is marked as private.
  - date
    OBJECT. Contains start/end dates and times.
  - travelTime
    OBJECT. Outward and return travel times. Can be null if disabled.
  - location
    OBJECT. The physical or virtual location of the appointment.
  - recurrence
    OBJECT. Details for recurring events (Interval as INT, Start/End as DATE).
  - reminder
    OBJECT. The reminder is a setting to provide a notification before the appointment begins. Uses INT for timeBefore, STRING for recipients, ARRAY(of STRINGS) for types, and BOOLEAN for confirmedOnly.
  - groups
    ARRAY. Groups participating in the appointment (ID and name).
  - users
    ARRAY. Users participating in the appointment (ID, userName, firstName, lastName, email).
  - resources
    ARRAY. Resources (rooms, cars) associated with the appointment. Each resource has an ID and name represented as STRING.
  - contacts
    ARRAY. Contacts linked to the appointment including their individual confirmation status.
  - showFollowUpStatus
    BOOLEAN. Must be used with contacts parameter. Adds two fields to each contact in the contacts array: followUpAvailable represented as BOOLEAN and followUpStatus represented as STRING (returns null if property feedback is not configured).
  - estate
    OBJECT. The estate associated with the appointment.
  - project
    OBJECT. A project associated with the appointment.
  - conflicts
    OBJECT. Information regarding schedule overlaps for users or resources.
- filter
  - startDate
    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. Filter by cancelled (true) or not cancelled (false) entries.
  - isDone
    BOOLEAN. Filter by completed (true) or not completedf (false) entries.
  - isRecurrent
    BOOLEAN. Filter by recurring (true) or single (false) entries.
  - userIds
    ARRAY. Filter by specific user IDs (Array of strings)..
  - groupIds
    ARRAY. Filter by specific group IDs (Array of strings).
  - notes
    ARRAY. 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 parameter

Present only when included in the data request parameter.

id
STRING. Appointment ID as string.
createdBy
STRING. Raw creator value from the record. Not explicitly guarded against being empty or null in the source — it simply reflects the raw stored value.
modified
STRING (ISO-8601, UTC). Falls back to the creation date if “modified” is empty, and further falls back to “0001-01-01T00:00:00+00:00” if both are empty.
subject
STRING. Set to “” if the appointment is private and the current user is not one of its responsible users/groups (see Privacy anonymization).
notes
STRING. Same anonymization behavior as subject.
type
OBJECT {value, label}. label is the translated (i18n) value of value.
status
OBJECT {value, label}. Computed via AppointmentStatusConverter; label is the translated value.
confirmationStatus
STRING. Aggregated/overall confirmation status across all linked (and access-permitted) contacts. Empty string if there are no linked contacts, or if the appointment is private and the user is not permitted (anonymized). Requires the acting user to have Address module access; otherwise no contacts are considered and the value stays empty.
private
BOOLEAN. true/false based on the record’s private flag.
date
OBJECT {start, end, allDay}. start/end are ISO-8601 datetime strings converted to UTC. allDay is boolean.
travelTime
OBJECT {outward, return} OR NULL. Null if “allow transit time” is not enabled on the appointment. Otherwise an object with outward/return in minutes.
location
OBJECT {type, value} OR NULL. Null if there is no location resource type set and the location text is empty. Set to null (anonymized) for private appointments the user isn’t part of.
recurrence
OBJECT {type, interval, start, end, exceptions} OR NULL. Null if the appointment is not recurring. Within the object, end is itself nullable (null when the recurrence has no defined end date). exceptions is a string array, always present (possibly empty).
reminder
OBJECT {timeBefore, recipients, confirmedOnly, types} OR NULL. Null if no reminder value is set on the appointment. Set to null (anonymized) for private appointments the user isn’t part of. timeBefore is in minutes; types is a subset of [“email”,”popup”,”push”,”sms”].
groups
ARRAY of {id, name}. Responsible groups for the appointment. Can be an empty array.
users
ARRAY of {id, userName, firstName, lastName, email}. Only active (non-deactivated) users are included. Can be an empty array.
resources
ARRAY of {id, name}. Resolved from the calendar’s resource single-select field.
contacts
ARRAY of {id, confirmationStatus?, followUpAvailable?, followUpStatus?}. See contacts sub-fields below. Set to [] (anonymized) for private appointments the user isn’t part of, if the user has no Address module access, or if there are no linked/permitted contacts.
estate
OBJECT {id} OR NULL. Null if there is no linked estate the user has access to, if the user lacks Estate module access, or (anonymized) if the appointment is private and the user isn’t part of it. Only the first linked, permitted estate ID is returned.
project
OBJECT {id} OR NULL. Null if no project number is set on the record.
conflicts
OBJECT {contacts, users, resources, estates} (each an array of {id}). Only included for single-appointment requests. All four arrays are empty — without even computing conflicts — if the appointment is private or recurring. Otherwise populated from the conflict-detection service.

`contacts` sub-fields

id
STRING. Always present (one entry per linked, access-permitted contact).
confirmationStatus
STRING. Only present if data also includes confirmationStatus.
followUpAvailable
BOOLEAN. Only present if data also includes showFollowUpStatus.
followUpStatus
STRING OR NULL. Only present if data also includes showFollowUpStatus; null when automatic feedback is not active for the appointment.

Note: contacts are additionally filtered by Address-module access control — a linked address only appears in contacts (and thus can only contribute to confirmationStatus) if the current user has read access to it.

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"
                }
            }
        ]
    }
}

—————–
—————-

ALT:

————————————
————————————

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 maximum number of appointments that can be queried at one time is 500. To avoid this restriction, please query smaller periods of time in which there are less than 500 appointments.

The parameter is divided into two: data and filter