List References

An appointment can be linked to forms and to files of the medical documentation. These links are not part of the appointment object. You fetch them separately through this endpoint.

Returns the references of an appointment.

Required scopes: appointments. The targets of a type only appear if your API access additionally has the matching scope: forms for the types Form and FormCustomer, medicals for the type MedicalFile. If the scope is missing, the references of that type are missing from the list.

Note: References whose target the client may not see are filtered out silently. meta.total therefore counts only the references visible to the client, not everything stored. Targets are not visible if they are deleted, if their scope is missing, if the owning user of the API access lacks permission for them, or if their customer is in a tenant that is not released to the owning user of the API access (only with the Mandanten add-on).

Note: Another user's private appointment without a share shows no content in the calendar. For this case the endpoint responds with 200 OK, data: [], and meta.total: 0 — not with an error.

Request

GET /api/oauth/v2/resource/appointments/{uuid}/references

Header

Header	Value
Authorization	Bearer {access_token}

URL parameters

Parameter	Type	Required	Description
uuid	string	Yes	Unique appointment ID

Query parameters

Parameter	Type	Required	Description
offset	integer	No	Start position (default: 0)
limit	integer	No	Number of results (default: 50, max: 200)

The references are sorted in the order in which they were created.

Response

Success (200 OK)

{
  "data": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "type": "Form",
      "target": "c3d4e5f6-a7b8-9012-cdef-234567890123",
      "createdAt": "2026-10-12T09:30:00+02:00"
    },
    {
      "id": "d4e5f6a7-b8c9-0123-def0-345678901234",
      "type": "MedicalFile",
      "target": "e5f6a7b8-c9d0-1234-ef01-456789012345",
      "createdAt": "2026-10-12T09:42:00+02:00"
    }
  ],
  "meta": {
    "total": 2,
    "offset": 0,
    "limit": 50
  }
}

If the appointment has no references, data is an empty list.

Response fields

Field	Type	Description
data[].id	string (UUID)	Unique reference ID
data[].type	string	Type of the linked target: Form, FormCustomer, or MedicalFile
data[].target	string (UUID) | null	UUID of the linked record, without an embedded short designation. You resolve it by type with GET /forms/{uuid} (Form), GET /forms/customers/{uuid} (FormCustomer), or GET /files/{uuid} (MedicalFile)
data[].createdAt	string (ISO 8601) | null	Time at which the reference was created
meta.total	integer	Number of references visible to the client
meta.offset	integer	Current start position
meta.limit	integer	Number of returned entries

Beispiele

bash

curl -X GET "https://my.offisy.at/api/oauth/v2/resource/appointments/b2c3d4e5-f6a7-8901-bcde-f01234567890/references?offset=0&limit=50" \
  -H "Authorization: Bearer {access_token}"

Server

Client-ID

Client-Secret

Parameter

uuid *string

offset integer

limit integer

Zuerst Token anfordern

Possible errors

Status	Code	Description
401	invalid_client	Invalid or missing access token
403	insufficient_scope	Scope appointments not present
403	access_denied	The owning user of the API access lacks the required permission for the appointment, or the appointment belongs to another company
404	not_found	Appointment not found