# API Reference
## Getting Started
### Introduction
Welcome to the Clipboard API reference.
The Clipboard API allows you to access various resources from your school's Clipboard account, allowing you to build integrations, apps and other services using the wealth of extracurricular data.
The API uses the standard [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer) architecture.
### OpenAPI Specification
The Clipboard API is also described by an [OpenAPI](https://www.openapis.org/) specification. You can browse it as an [interactive API reference](/api-reference.html ":ignore"), or download [`openapi.yaml`](/openapi.yaml ":ignore") for use with your own tooling.
The specification is being rolled out endpoint by endpoint and does not yet cover the whole API. This written documentation remains authoritative for endpoints not yet included.
### Access Terms
By accessing the Clipboard API, you agree to be bound by our [Integration Data Processing Terms](https://www.clipboard.app/legal/integration-data-processing-terms), which govern the collection, sharing, and processing of data in connection with your integration with Clipboard. If you do not agree to these terms, you must not access or use the Clipboard API.
### Base URL
The Clipboard API is accessed at the following URL.
```url
https://api.clipboard.app
```
All endpoints build off this base URL, e.g. `GET https://api.clipboard.app/sessions`.
### Authentication
The Clipboard API uses an [API token](https://en.wikipedia.org/wiki/Access_token) to authenticate requests. You can view, manage and provision tokens on the Clipboard [Integration page](https://go.clipboard.app/integration/api). Only IT Admins can access this.
API tokens unlock access to your school's extracurricular data, so be sure to keep them secure! Don't share them in publicly accessible areas, via insecure channels, and so on.
The current version of the Clipboard API uses [Bearer Authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/) to authenticate each HTTP request. You need to provide an `Authorization` header on each request, like below, replacing `YOUR_TOKEN` with the token you have provisioned from the Clipboard App.
```http
Authorization: Bearer YOUR_TOKEN
```
All API requests need to be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over HTTP will be redirected to HTTPS and calls made with no authentication will fail.
### Errors
Clipboard uses standard HTTP response codes to indicate success or failure of an API request.
In general:
- `2xx` indicates success
- `4xx` indicates an error due to what was provided in the request (e.g. an invalid parameter)
- `5xx` indicates an error with Clipboard's servers
#### Status Codes
| Code | Explanation |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200 - OK` | Success. |
| `401 - Unauthorized` | No valid API token was provided. |
| `403 - Forbidden` | The API token doesn't have permissions to perform the request. |
| `404 - Not Found` | The requested resource doesn't exist. |
| `409 - Conflict` | The request conflicts with another request. Most commonly this is when creating something that already exists (e.g. a duplicate of something that should be unique). |
| `422 - Unprocessable Entity` | The request was unacceptable because of what was provided. |
| `429 - Too Many Requests` | Too many requests were made to the API too quickly. See [Rate Limiting](?id=rate-limiting) for more details. |
| `5xx - Server Errors` | Something went wrong on Clipboard's end. Please contact Clipboard Support. |
### Pagination
All of the "Get" endpoints support [pagination](https://en.wikipedia.org/wiki/Pagination), allowing you to specify the number of records to return, and which page of records to return.
#### Parameters
The below query parameters can be provided for pagination.
| Parameter | Type | Description |
| ------------ | ------ | ----------------------------------------------------------------------------- |
| `page` | number | A cursor, specifying the page of data to return, starting at 1. |
| `pageLength` | number | A limit on the number of objects to be returned, typically between 1 and 100. |
#### Response Body Format
A successful response from "Get" endpoints will take this form.
| Property | Type | Description |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------- |
| `data` | array | The list of objects returned by the API call. |
| `pagination` | object | The pagination details, including the current page and total number of records. `paginationData` will be phased out |
#### Pagination Object Format
The `pagination` object takes the following form.
| Property | Type | Description |
| ------------- | ------ | ----------------------------------------------------------------------- |
| `currentPage` | number | The page of results that has been specified in the request. |
| `lastPage` | number | The total number of pages of results for the given query. |
| `pageLength` | number | The number of records to include per page, as specified by the request. |
| `numRecords` | number | The total number of records that exist, given the provided parameters. |
### Updated Before or After
A number of the "Get" endpoints support `updatedBefore` and `updatedAfter` query parameters.
Both parameters expect a timestamp in ISO format (see more below on timestamps).
The two parameters are used (either separately or together) to filter records that have been updated before and/or after a certain timestamp.
If you're periodically fetching data from Clipboard, it is recommended you use these parameters.
The following endpoints support the `updatedBefore` and `updatedAfter` query parameters:
- [Get Sessions](?id=get-sessions)
- [Get Teams](?id=get-teams)
- [Get Attendance Records](?id=get-attendance-records)
- [Get Incidents](?id=get-incidents)
- [Get Pre Explained Absences](?id=get-pre-explained-absences)
### Custom Fields Metadata
Some "Get" endpoints support `includeCustomFieldsMetadata` query parameters.
This parameter is an optional boolean input defaulting to false, with one exception: the `ics` and `iCalendar` formats of [Get Sessions](?id=get-sessions) default to true.
When set to true the endpoint will return an additional object where the key matches the key in the customFieldsData returned in the data object.
The values within customFieldsMetadata are as follows.
| Attribute | Type | Description |
| ----------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label` | string | The label of the field. |
| `dataType` | `short-text`\|`time`\|`single-select`\|`staff`\|`student` | Type of field which will determine how the field should be interpreted: - `short-text`\|`single-select`: Can be presented as the string returned
- `time`: returned in HH:mm format in the school's time zone
- `staff`\|`student`: returned as an array of staff or student Clipboard IDs. These will need to be searched against data obtained from [GET Users](?id=get-users) and [GET Students](?id=get-students)
|
| `showToUserTypes` | string[] | Which user types this field should be displayed to. Currently supports `admin`\|`manager`\|`staff`\|`guardian`\|`student`. |
| `showAfterField` | string | Identifier of the field before the custom field in sort order. |
The following endpoints support `includeCustomFieldsMetadata`:
- [Get Sessions](?id=get-sessions)
### Timestamps
All timestamp query parameters need to be provided in [ISO timestamp](https://en.wikipedia.org/wiki/ISO_8601) format. All timestamps returned from the Clipboard API are in ISO timestamp format set at [UTC time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time). It's important to note that these timestamps are not in the time zone of your school. You will need to convert the timestamps to your time zone as you see fit.
### Query Parameters
If this documentation specifies that a query parameter requires an array, this means the Clipboard API expects a stringified JSON array as a query parameter.
### Versioning
At present, when a [backwards-incompatible](https://en.wikipedia.org/wiki/Backward_compatibility) change is made to the API, Clipboard will inform all API consumers with multiple months' notice.
As usage of the API grows and evolves, Clipboard will introduce versioning to prevent issues relating to backwards compatibility.
## Rate Limiting
The Clipboard API enforces rate limiting to ensure fair usage and maintain the stability of our services. Rate limits are in place to prevent both intentional and unintentional denial of service incidents. When the rate or burst limit of API requests is exceeded, the API will respond with a `429 - Too Many Requests` HTTP status code.
### Handling `429 - Too Many Requests`
If your request encounters a rate limit, it is essential to implement a retry mechanism to handle this error effectively. We strongly recommend using the **exponential backoff** strategy for retries. This method involves progressively increasing the delay between retry attempts, which helps manage the load on the API and enhances the success rate of your subsequent requests.
#### Exponential Backoff Algorithm:
1. Make a request to the API.
2. If the request returns a `429` error, wait 1 second, then retry the request.
3. If the request fails again with a `429`, wait 2 seconds (2^1), then retry the request.
4. Continue to double the wait time (e.g., 4 seconds, 8 seconds) for each subsequent `429` error.
5. Optionally, set a maximum number of retries or a maximum wait time to avoid infinite loops.
For a practical implementation of exponential backoff, refer to this [Exponential Backoff and Jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) article from AWS, which provides detailed explanations and examples.
### Best Practices
- **Monitor Your Requests:** Keep track of the number of requests made to ensure you remain within the rate limits.
- **Spread Out Requests:** If feasible, distribute your requests more evenly to prevent spikes of traffic.
- **Implement Intelligent Retries:** Use an intelligent retry mechanism, such as exponential backoff, to efficiently handle rate limit errors.
The implementation of rate limits is a common practice across the industry to ensure equitable access and service reliability for all users. By adhering to these practices, you can maintain seamless integration with The Clipboard API.
## Sessions
### The Session object
A **Session** is essentially a calendar event which could correspond to anything from a music lesson to a sports match.
If a Session is to have a result associated with it (e.g. a sports match), it is referred to as a **Fixture**.
The fields returned for a Session are documented in the [interactive API reference](/api-reference.html ":ignore"), under the response schema of each Sessions endpoint.
### Get Sessions
Returns a list of Sessions, filtered by the provided query parameters. The Sessions are returned in chronological order.
The maximum page length is 1000 and the default is 100.
With `format=ics` or `format=iCalendar` the same Sessions are returned as an iCalendar (RFC 5545) document with the `text/calendar` media type, served as an attachment named `cal.ics`. The filtering parameters below still apply, except that the date range is fixed to one month before and three months after the current timestamp and the page length to 200. Each Session's custom fields are folded into its event description unless `includeCustomFieldsMetadata=false` is provided.
#### Parameters
| Parameter | Type | Description |
| ----------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `activityIds` | number[] | Only return Sessions for Activities with the provided IDs. |
| `departmentIds` | number[] | Only return Sessions for Departments with the provided IDs. |
| `locationIds` | number[] | Only return Sessions held in the provided location IDs. |
| `startDateTime` | string | Only return Sessions that intersect the range of the `startDateTime` and `endDateTime` timestamps. Must provide `endDateTime` as well. If both values are not provided a default range of 4 weeks before the current timestamp and 4 weeks after the current timestamp will be used instead. If a `teamId` is provided the range is expanded to 6 months after the current timestamp. |
| `endDateTime` | string | The end timestamp of the range to return Sessions within. |
| `cancelled` | boolean | Whether to return Sessions that are only cancelled or only not cancelled. |
| `bye` | boolean | Whether to return Fixtures that are only byes or not byes. |
| `sisIds` | string[] | Only return the Sessions that have students with the provided SIS IDs assigned to them. |
| `teamId` | number | Only return the Sessions which include provided team Id. |
| `scored` | boolean | If `true`, only return Fixtures. If `false`, only return Sessions. Else return both types of Session. |
| `includeStatuses` | array of 'confirmed' \| 'unconfirmed' \| 'draft' | Only return Fixtures that match one of the statuses in this array. |
| `includeTeams` | boolean | Whether to also include the `teams` (and `students`) array for each Session in the response. |
| `includeStaff` | boolean | Whether to also include the `assignedStaff` array (containing all assigned staff) for each Session in the response. |
| `includeRoundName` | boolean | Whether to, for Fixtures, also include the round name of each Fixture. |
| `includeSisIds` | boolean | Used in conjunction with `sisIds`. Whether to include an array of matching student `sisIds` for each Session in the response. |
| `includeCustomFieldsMetadata` | boolean | Whether to include the relevant custom fields metadata in the response. Defaults to `false` for JSON responses. When `format` is `ics` or `iCalendar` it defaults to `true`, so custom fields are included in the calendar event descriptions unless you set this parameter to `false`. |
| `excludeSessionsWithTeams` | boolean | Optional parameter that defaults to `false`. If set to `true`, only Sessions that are not associated with any team will be returned. |
| `updatedBefore` | string | See [Updated Before or After](?id=updated-before-or-after) |
| `updatedAfter` | string | See [Updated Before or After](?id=updated-before-or-after) |
| `format` | 'ics' \| 'iCalendar' | Return the matching Sessions as an iCalendar feed instead of the JSON response, as described above. |
#### **Request**
```bash
curl \
--request GET \
--url 'https://api.clipboard.app/sessions?startDateTime=2021-07-01T13:00:00Z&endDateTime=2021-08-31T13:00:00Z&includeStaff=true' \
--header 'Authorization: Bearer YOUR_TOKEN'
```
#### **Response**
```json
{
"data": [
{
"id": 358,
"title": "Senior Band",
"notes": "",
"opponent": null,
"bye": false,
"cancelled": false,
"scored": false,
"hexColor": "ffe247",
"startDateTime": "2021-07-01T21:30:00.000Z",
"endDateTime": "2021-07-01T23:00:00.000Z",
"studentParentNotes": "",
"creatorUserId": 1,
"seriesId": 73,
"organisationScore": null,
"opponentScore": null,
"result": null,
"remindStaff": true,
"activity": {
"id": 11,
"name": "Band",
"department": {
"id": 4,
"name": "Music"
},
"colour": 4,
"hexColor": "ffe247"
},
"feedback": [],
"assignedStaff": [
{
"id": 4,
"firstName": "Charlotte",
"lastName": "Williams",
"sisId": null,
"externalId": "CWILL1",
"secondaryExternalId": null
}
],
"locationData": {
"id": 8,
"name": "North Sydney Oval",
"address": "2 Fig Tree Lane, North Sydney NSW 2060",
"latitude": -33.823083,
"longitude": 151.209291,
"owner": {
"id": 1,
"name": "Clipboard College",
"acronym": "CBC",
"shortName": "CB College",
"state": "NSW"
}
},
"teams": [],
"students": [],
"status": "confirmed"
},
...
]
}
```
### Get a Session
Returns the details of a specific Session. Supply the unique Clipboard identifier of the Session.
Provide the ID of the Session as a path parameter, like the example below.
#### Parameters
| Parameter | Type | Description |
| ----------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `includeTeams` | boolean | Whether to also include the `teams` (and `students`) array for the Session in the response. |
| `includeStaff` | boolean | Whether to also include the `assignedStaff` array for the Session in the response. |
| `includeCustomFieldsMetadata` | boolean | Whether to include the relevant custom fields metadata in the response. Defaults to `false`; the metadata is only included when this parameter is set to `true`. |
#### **Request**
```bash
curl \
--request GET \
--url 'https://api.clipboard.app/sessions/358' \
--header 'Authorization: Bearer YOUR_TOKEN'
```
#### **Response**
```json
{
"data": {
"id": 358,
"title": "Senior Band",
"locationData": {
"id": 8,
"name": "North Sydney Oval",
"address": "2 Fig Tree Lane, North Sydney NSW 2060",
"latitude": -33.823083,
"longitude": 151.209291,
"owner": {
"id": 1,
"name": "Clipboard College",
"acronym": "CBC",
"shortName": "CB College",
"state": "NSW"
},
"subLocations": null
},
"notes": "",
"studentParentNotes": "",
"scored": false,
"opponent": null,
"opponentTeam": null,
"opponentOrganisation": null,
"bye": false,
"cancelled": false,
"startDateTime": "2021-07-01T21:30:00.000Z",
"endDateTime": "2021-07-01T23:00:00.000Z",
"creatorUserId": 1,
"organisationScore": null,
"opponentScore": null,
"displayScore": null,
"result": null,
"resultNotes": null,
"activity": {
"id": 11,
"name": "Band",
"department": {
"id": 4,
"name": "Music"
},
"hexColor": "ffe247"
},
"assignedStaff": [
{
"id": 4,
"firstName": "Charlotte",
"lastName": "Williams",
"sisId": null,
"externalId": "CWILL1",
"secondaryExternalId": null
}
],
"teams": [
{
"id": 15,
"name": "Senior Band",
"category": {
"id": 3,
"name": "Senior",
"sortOrder": 3
},
"subcategory": null,
"customFieldsData": {
"teams_colours": "Red and Blue"
}
}
],
"students": [
{
"id": 45,
"firstName": "Amy",
"lastName": "Chen",
"smsId": "CHEN0045",
"yearGroup": {
"id": 5,
"name": "Year 11"
}
}
],
"status": "confirmed",
"roundName": null,
"customFieldsData": {
"sessions_equipment": "Bring music stands"
},
"optional": false
},
"customFieldsMetadata": {
"sessions_equipment": {
"label": "Equipment Needed",
"dataType": "short-text",
"showAfterField": "notes",
"showToUserTypes": ["admin", "manager", "staff", "student", "guardian"]
},
"teams_colours": {
"label": "Colours",
"dataType": "short-text",
"showAfterField": null,
"showToUserTypes": ["admin", "manager", "staff", "student", "guardian"]
}
}
}
```
### Post Sessions (Early Access)
> Interested in using this feature?
> Contact for more details.
Provided an array of sessions, will create sessions for your organisation.
#### Parameters
| Attribute | Type | Description |
| ----------------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email` | string | The email of the user that the create action will be performed on behalf of. |
| `sendStaffNotifications` | boolean | Notifications will be sent to the affected staff that the session was created. |
| `sendStudentsAndGuardiansNotifications` | boolean | Notifications will be sent to the affected students and guardians that the session was created. |
| `sessions` | Session[] | An array of the sessions to be created. |
| `title` | string | The title of the session. |
| `activityId` | number | The activity id that will be assigned to the session. |
| `startDateTime` | string | The start date and time of the session, provided in UTC. |
| `endDateTime` | string | The end date and time of the session, provided in UTC. |
| `teamIds` | number[] \| undefined | An array of the team ids assigned to the session. If team ids are provided, studentIds cannot be provided. |
| `studentIds` | number[] \| undefined | An array of the student ids assigned to the session. If student ids are provided, teamIds cannot be provided. |
| `staffIds` | number[] \| undefined | An array of the staff ids assigned to the session. |
| `notes` | string \| undefined | Internal notes for assigned staff to view on the session. |
| `studentParentNotes` | string \| undefined | External notes for assigned students and corresponding parents / guardians to view on the session. |
| `remindStaff` | boolean \| undefined | Trigger staff reminders for this session. |
| `optional` | boolean \| undefined | Mark the session as optional for the students / teams assigned. |
| `locationId` | number \| undefined | Assign the session to the provided location. If locationName is provided, locationId cannot be provided |
| `locationName` | string \| undefined | Assign the session to the provided location name. If the location does not exist, create a new location and assign the session to the new location. If locationId is provided, locationName cannot be provided. |
#### **Request**
```bash
curl \
--request POST \
--url 'https://api.clipboard.app/sessions' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"email": "Wallace@example.com",
"sendStaffNotifications": true,
"sendStudentsAndGuardiansNotifications": true,
"reasonForChange": "example reason",
"sessions": [{
"title": "Training",
"activityId": 1,
"startDateTime": "2025-01-15 19:30:00",
"endDateTime": "2025-01-15 20:00:00",
"teamIds": [2, 3],
"staffIds": [1, 2],
"notes": "Arrive 30 minutes before the start time",
"studentParentNotes": "We are on the lower field",
"remindStaff": true,
"optional": false,
"locationId": 32
},
{
"title": "A new event!",
"activityId": 2,
"startDateTime": "2025-01-15 19:30:00",
"endDateTime": "2025-01-15 20:00:00",
"studentIds": [1, 2, 3, 4, 5],
"staffIds": [3, 4],
"locationName": "A cool new location"
}]
}'
```
#### **Response**
```json
{
"createdSessions": [
{
"id": 1234
},
{
"id": 1235,
"locationId": 33
}
]
}
```
### Patch Sessions (Early Access)
> Interested in using this feature?
> Contact for more details.
Provide an array of existing sessions with fields to update from your organisation, those sessions will be updated.
#### Parameters
| Attribute | Type | Description |
| ----------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `email` | string | The email of the user that the update action will be performed on behalf of. |
| `sendStaffNotifications` | boolean | Notifications will be sent to the affected staff that the session was updated. |
| `sendStudentsAndGuardiansNotifications` | boolean | Notifications will be sent to the affected students and guardians that the session was updated. |
| `sessions` | Session[] | An array of the sessions to be updated. |
| `id` | number | The id of the session to be updated. |
| `title` | string | The title of the session. |
| `activityId` | number | The activity id that will be assigned to the session. |
| `startDateTime` | string | The start date and time of the session, provided in UTC. |
| `endDateTime` | string | The end date and time of the session, provided in UTC. |
| `teamIds` | number[] \| undefined | An array of the team ids assigned to the session. If team ids are provided, studentIds cannot be provided. |
| `studentIds` | number[] \| undefined | An array of the student ids assigned to the session. If student ids are provided, teamIds cannot be provided. |
| `staffIds` | number[] \| undefined | An array of the staff ids assigned to the session. |
| `notes` | string \| undefined | Internal notes for assigned staff to view on the session. |
| `studentParentNotes` | string \| undefined | External notes for assigned students and corresponding parents / guardians to view on the session. |
| `remindStaff` | boolean \| undefined | Trigger staff reminders for this session. |
| `optional` | boolean \| undefined | Mark the session as optional for the students / teams assigned. |
| `location` | number \| null \| undefined | Assign the session to the provided location. Otherwise unassign the currently assigned location. |
| `cancelled` | boolean \| undefined | Sets the cancelled status of the session. |
#### **Request**
```bash
curl \
--request PATCH \
--url 'https://api.clipboard.app/sessions' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"email": "Wallace@example.com",
"sendStaffNotifications": true,
"sendStudentsAndGuardiansNotifications": true,
"reasonForChange": "example reason",
"sessions": [{
"id": 1,
"title": "Training",
"activityId": 1,
"startDateTime": "2025-01-15 19:30:00",
"endDateTime": "2025-01-15 20:00:00",
"teamIds": [2, 3],
"staffIds": [1, 2],
"notes": "Arrive 30 minutes before the start time",
"studentParentNotes": "We are on the lower field",
"remindStaff": true,
"optional": false,
"location": 32
},
{
"id": 62
"title": "A new event!",
"activityId": 2,
"studentIds": [1, 2, 3, 4, 5],
"teamIds": [],
"staffIds": [3, 4],
"location": null
}]
}'
```
#### **Response**
```json
{}
```
### Delete Sessions (Early Access)
> Interested in using this feature?
> Contact for more details.
Deletes existing sessions from your organisation.
#### Parameters
| Attribute | Type | Description |
| --------------------------------------- | --------- | ----------------------------------------------------------------------------------------------- |
| `email` | string | The email of the user that the delete action will be performed on behalf of. |
| `sendStaffNotifications` | boolean | Notifications will be sent to the affected staff that the session was deleted. |
| `sendStudentsAndGuardiansNotifications` | boolean | Notifications will be sent to the affected students and guardians that the session was deleted. |
| `sessionIds` | Session[] | An array of the session ids that are to be deleted. |
#### **Request**
```bash
curl \
--request DELETE \
--url 'https://api.clipboard.app/sessions' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"email": "Wallace@example.com",
"sendStaffNotifications": true,
"sendStudentsAndGuardiansNotifications": true,
"reasonForChange": "example reason",
"sessionIds": [1, 2, 3]
}'
```
#### **Response**
```json
{}
```
## Teams
### The Team object
A **Team** is the Clipboard term for any team, ensemble or group of students.
| Attribute | Type | Description |
| ------------------------------------------- | -------------- | --------------------------------------------------------------------------- |
| `id` | number | The primary key that uniquely identifies the Team in Clipboard. |
| `name` | string | The name of the Team. |
| `sisId` | string | The team's SIS ID. |
| `hidden` | boolean | If the Team is hidden. |
| `category` | object | The optional Category of the Team (e.g. age group). |
| `id` | number | The primary key that uniquely identifies the Team Category in Clipboard. |
| `name` | string | The name of the Category. |
| `subcategory` | object | The optional Subcategory of the Team (e.g. age group). |
| `id` | number | The primary key that uniquely identifies the Team Subcategory in Clipboard. |
| `name` | string | The name of the Subcategory. |
| `activity` | object | The Activity the Team belongs to. |
| `id` | number | The primary key that uniquely identifies the Activity in Clipboard. |
| `name` | string | The name of the Activity. |
| `department` | object | The Department the Activity is within. |
| `sisCode` | string | The external SIS code for the Activity. |
| `id` | number | The primary key that uniquely identifies the Department in Clipboard. |
| `name` | string | The name of the Department. |
| `assignedStaff` | object[] | The list of assigned users. |
| `id` | number | The primary key that uniquely identifies the user in Clipboard. |
| `firstName` | string | The user's first name. |
| `lastName` | string | The user's last name. |
| `sisId` | string \| null | Optional external system identifier for integration purposes. |
| `students` | object[] | The students who are part of the Team. |
| `studentId` | number | The primary key that uniquely identifies the student in Clipboard. |
| `firstName` | string | The student's first name. |
| `legalFirstName` | string | The student's legal first name. |
| `lastName` | string | The student's last name. |
| `smsId` | string | The student's SIS ID. |
| `yearGroup` | object | The student's current year group. |
| `id` | number | The primary key that uniquely identifies the year group in Clipboard. |
| `name` | string | The name of the year group. |
| `boarder` | boolean | If the student is a boarder. |
| `captain` | boolean | If the student is the Team captain. |
| `jerseyNumber` | string | The jersey number of the student in the Team. |
| `positionId` | number | The Clipboard ID of the position the student has in the Team, if any. |
| `positions` | object[] | The positions in the Team. |
| `id` | number | The primary key that uniquely identifies the Team Position in Clipboard. |
| `name` | string | The position name. |
| `numberOfSlots` | number | The number of student slots the position can contain. |
### Get Teams
Returns a list of Teams, filtered by the provided query parameters.
Results are automatically limited to 50 Teams per page and the default is 15. A `pageLength` above 50 is accepted rather than rejected, but at most 50 Teams are returned per page.
#### Parameters
| Parameter | Type | Description |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `activityId` | number | Only return Teams for the Activity with the provided ID. |
| `departmentIds` | number[] | Only return Teams for Departments with the provided IDs. |
| `categoryId` | number | Only return Teams in the Category with the provided ID. |
| `hidden` | boolean | When set to true, it returns only hidden teams; when set to false, it returns non-hidden teams. Defaults to false. |
| `includeStaff` | boolean | If the users (staff members) assigned to the Teams should be returned. |
| `includeStudents` | boolean | If the students assigned to the Teams should be returned. |
| `includePositions` | boolean | If the positions in the Teams should be returned. |
| `sisIds` | string[] | Only return Teams for students with the provided SIS IDs. |
| `showAsOfDate` | string | Shows the students and assigned staff as at the UTC timestamp provided |
| `userIds` | number[] | Only return Teams for assigned staff members with the provided IDs. |
| `updatedBefore` | string | See [Updated Before or After](?id=updated-before-or-after) |
| `updatedAfter` | string | See [Updated Before or After](?id=updated-before-or-after) |
#### **Request**
```bash
curl \
--request GET \
--url 'https://api.clipboard.app/teams?sisIds=["clipboard.ADAMS0"]&page=1&pageLength=30' \
--header 'Authorization: Bearer YOUR_TOKEN'
```
#### **Response**
```json
{
"data": [
{
"id": 81,
"name": "1sts",
"playersRanked": false,
"category": {
"id": 1,
"name": "Senior"
},
"activity": {
"id": 3,
"name": "Hockey",
"sisCode": "HK",
"department": {
"id": 2,
"name": "Sport"
}
},
"assignedStaff": [],
"students": [],
"positions": []
},
...
],
"pagination": {
"currentPage": 1,
"lastPage": 1,
"numRecords": 2,
"pageLength": 30
}
}
```
### Get a Team
Returns the details of a Team. Supply the unique Clipboard identifier of the Team.
Provide the ID of the Team as the parameter in the URL, like the example below.
#### Parameters
| Parameter | Type | Description |
| -------------- | ------ | ---------------------------------------------------------------------- |
| `showAsOfDate` | string | Shows the students and assigned staff as at the UTC timestamp provided |
#### **Request**
```bash
curl \
--request GET \
--url 'https://api.clipboard.app/teams/12973 \
--header 'Authorization: Bearer YOUR_TOKEN'
```
#### **Response**
```json
{
"data": {
"id": 12973,
"name": "9C's",
"category": {
"id": 2,
"name": "Middle"
},
"activity": {
"id": 3,
"name": "Hockey",
"department": {
"id": 2,
"name": "Sport"
},
"accessRights": {
"moveStudentsWithoutApproval": false
}
},
"assignedStaff": [
{
"id": 34,
"firstName": "Delia",
"lastName": "Raymond"
}
],
"students": [
{
"id": 624,
"studentId": 5,
"firstName": "Luca",
"legalFirstName": null,
"lastName": "Abbadelli",
"email": "lucaabbadelli@clipboard.app",
"yearGroup": {
"id": 3,
"name": "Year 9"
},
"smsId": "ABBAD0635",
"boarder": false,
"captain": false,
"jerseyNumber": null,
"guardians": [],
"medicalConditions": [],
"sortOrder": null,
"positionId": null,
"absentToday": false,
"absentReason": ""
},
...
],
"positions": [],
"studentSortType": "alphabetical-lastname"
}
}
```
## Students
### The Student object
| Attribute | Type | Description |
| ---------------- | ------ | ---------------------------------------------------------------------- |
| `id` | number | The primary key that uniquely identifies the Student **in Clipboard**. |
| `legalFirstName` | string | The legal first name of the Student. |
| `firstName` | string | The preferred first name of the Student. |
| `lastName` | string | The last name of the Student. |
| `sisId` | string | The ID that identifies the Student in the SIS. |
| `secondarySisId` | string | Optional secondary SIS ID. Can be used in SSO and certain integrations |
| `yearGroupId` | number | The Clipboard ID of the student's year group. |
### Get Students
Returns a list of Students. This endpoint might be useful to get the student Clipboard IDs in order to be able to post pre-explained absences. This endpoint supports pagination.
#### Parameters
| Parameter | Type | Description |
| ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `current` | boolean | Optional parameter that defaults to true. If set to true, will only return current students. If set to false, will only return non-current students. |
| `sisIds` | string[] | Optional parameter. Only return students for those with the provided SIS IDs. |
| `page` | number | Optional page parameter. If a page is not provided, it will default to page 1. |
| `pageLength` | number | Optional page length parameter with a maximum of 200. If a page length is not provided, it will default to a page size of 100. |
#### **Request**
```bash
curl \
--request GET \
--url 'https://api.clipboard.app/students?current=true&page=1&pageLength=30' \
--header 'Authorization: Bearer YOUR_TOKEN'
```
#### **Response**
```json
{
"data": [
{
"id": 3,
"firstName": "Carmina",
"lastName": "Abbadelli",
"legalFirstName": null,
"sisId": "ABBAD0129",
"secondarySisId": "clipboard.ABBAD2",
"yearGroupId": 1
},
...
],
"pagination": {
"currentPage": 1,
"lastPage": 41,
"numRecords": 1203,
"pageLength": 30
}
}
```
## Student Teams
### The Student Team object
A **Student Team** is the Clipboard term for a Student's assignment to a Team.
| Attribute | Type | Description |
| ------------------------------------- | ------ | ----------------------------------------------------------------------------------- |
| `id` | number | The primary key that uniquely identifies the Student Team in Clipboard. |
| `student` | object | The Student of the Student Team pairing. |
| `id` | number | The primary key that uniquely identifies the Student in Clipboard. |
| `fullName` | string | The full name of the Student. |
| `smsId` | string | The id of the Student in the School's Student Information System. |
| `team` | object | The Team of the Student Team pairing. |
| `id` | number | The primary key that uniquely identifies the Team in Clipboard. |
| `name` | string | The name of the Team. |
| `sisId` | string | The team's SIS ID. |
| `activity` | object | The Activity of the Team |
| `id` | number | The primary key that uniquely identifies the Team Subcategory in Clipboard. |
| `name` | string | The name of the Subcategory. |
| `startDateTime` | string | The date time the Student joined the Team (or `null` for older Student Teams). |
| `endDateTime` | string | The date time the Student left the Team (or `null` for Students still in the Team). |
### Get Student Teams
Returns a list of Student Teams, filtered by the provided query parameters. The endpoint supports pagination and it is highly recommended that it is used when querying larger data sets since the number of records returned will be limited.
The maximum page length is 300 and the default is 100.
#### Parameters
| Parameter | Type | Description |
| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `activityId` | number | Only return Student Teams for the Activity with the provided ID. |
| `studentIds` | number[] | Only return Student Teams for the specified Student's using Clipboard's primary key |
| `startDateTime` | string | Only return Student Teams that fall between the range of the `startDateTime` and `endDateTime` UTC timestamps. Must provide `endDateTime` as well. |
| `endDateTime` | string | The end timestamp of the range to return Student Teams within. |
| `page` | number | Optional page parameter. If page is not provided, it will default to page 1. |
| `pageLength` | number | Optional page length parameter. If page length is not provided, it will default to a page length of 100. |
#### **Request**
```bash
curl \
--request GET \
--url 'https://api.clipboard.app/student-teams?startDateTime=2021-10-01T10:00:00Z&endDateTime=2021-10-31T10:00:00Z&page=1&pageLength=30' \
--header 'Authorization: Bearer YOUR_TOKEN'
```
#### **Response**
Response without pagination:
```json
{
"data": [
{
"id": 3,
"student": {
"id": 40,
"smsId": "BUCKNER0033",
"fullName": "Donovan Buckner"
},
"team": {
"id": 7,
"name": "7E's",
"activity": {
"id": 5,
"name": "Basketball"
}
},
"startDateTime": "2021-09-13T06:21:42.638Z",
"endDateTime": null
},
...
]
}
```
Response with pagination enabled:
```json
{
"data": [
{
"id": 3,
"student": {
"id": 40,
"smsId": "BUCKNER0033",
"fullName": "Donovan Buckner"
},
"team": {
"id": 7,
"name": "7E's",
"activity": {
"id": 5,
"name": "Basketball"
}
},
"startDateTime": "2021-09-13T06:21:42.638Z",
"endDateTime": null
},
...
],
"pagination": {
"currentPage": 1,
"lastPage": 40,
"numRecords": "409",
"pageLength": 30
}
}
```
## Attendance Records
### The Attendance Record object
An **Attendance Record** is a record of a student's attendance or non-attendance at a Session.
| Attribute | Type | Description |
| ------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------- |
| `id` | number | The primary key that uniquely identifies the Attendance Record in Clipboard. |
| `absent` | boolean | If this is a record of the student's absence or not. |
| `explained` | boolean | For an absence, if it is an explained absence or not (e.g. the student or parent/carer had provided a reason). |
| `comment` | string \| null | A comment on the Attendance Record, left by the staff member who recorded it. |
| `addedToRoll` | boolean | If `true`, this student was added retrospectively to the roll that this attendance was recorded on. |
| `attendanceFlags` | object[] | The list of additional flags added to this Attendance Record. |
| `id` | string | The primary key that uniquely identifies the Attendance Flag in Clipboard. |
| `name` | string | The name of the Attendance Flag. |
| `student` | object | The student who this Attendance Record is for. |
| `id` | number | The primary key that uniquely identifies the student in Clipboard. |
| `firstName` | string | The student's first name. |
| `legalFirstName` | string \| null | The student's legal first name. |
| `lastName` | string | The student's last name. |
| `smsId` | string \| null | The student's SIS ID. |
| `yearGroup` | object | The student's current year group. |
| `id` | number | The primary key that uniquely identifies the year group in Clipboard. |
| `name` | string | The name of the year group. |
| `session` | object | The Session that this Attendance Record is for. |
| `id` | number | The primary key that uniquely identifies the Session in Clipboard. |
| `title` | string \| null | The title of the Session. |
| `activity` | object | The Activity the Session (and therefore this Attendance Record) is for. |
| `id` | number | The primary key that uniquely identifies the Activity in Clipboard. |
| `name` | string | The name of the Activity. |
| `startDateTime` | string | The start timestamp for the Session. |
| `endDateTime` | string \| null | The end timestamp for the Session. |
| `team` | object \| null | The Team that the roll for this Attendance Record is for, if any. |
| `id` | number | The primary key that uniquely identifies the Team in Clipboard. |
| `name` | string | The name of the Team. |
| `category` | object \| null | The Category (e.g. age group) of the Team, if any. |
| `id` | number | The primary key that uniquely identifies the Team Category in Clipboard. |
| `name` | string | The name of the Category. |
| `roll` | object | The roll that this Attendance Record is part of. |
| `id` | number | The primary key that uniquely identifies the roll in Clipboard. |
| `timeMarked` | string \| null | The timestamp of when the roll was first marked. |
| `timeEdited` | string \| null | The timestamp of when the roll was last edited. |
| `markedByUser` | object \| null | The user who first marked the roll. |
| `id` | number | The primary key that uniquely identifies the User in Clipboard. |
| `firstName` | string | The user's first name. |
| `lastName` | string | The user's last name. |
| `sisId` | string \| null | The user's SIS ID, if it exists. |
| `editedByUser` | object \| null | The user who last edited the roll, if any. |
| `id` | number | The primary key that uniquely identifies the User in Clipboard. |
| `firstName` | string | The user's first name. |
| `lastName` | string | The user's last name. |
| `sisId` | string | The user's SIS ID, if it exists. |
| `updatedTimestamp` | string \| null | The time at which the Attendance Record was updated, if at all. |
| `updatedByUser` | object \| null | The user (staff member) who last updated the Attendance Record, if any. |
| `id` | number | The primary key that uniquely identifies the User in Clipboard. |
| `firstName` | string | The user's first name. |
| `lastName` | string | The user's last name. |
| `sisId` | string \| null | The user's SIS ID, if it exists. |
### Get Attendance Records
Returns a list of Attendance Records, filtered by the provided query parameters.
The maximum page length is 300 and the default is 30.
#### Parameters
| Parameter | Type | Description |
| --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `activityIds` | number[] | Only return Attendance Records for Activities with the provided IDs. |
| `departmentIds` | number[] | Only return Attendance Records for Departments with the provided IDs. |
| `studentSisIds` | string[] | Only return Attendance Records for students with the provided SIS IDs. |
| `timePeriod` | string | The simple time period string to fetch Attendance Records for. Possible values: `today` \| `yesterday` \| `last-week` \| `last-30-days` \| `last-90-days` \| `last-6-months` \| `this-year` \| `last-year` \| `custom`. To Use a `custom` timePeriod, provide a startDateTime and endDateTime otherwise a default timePeriod will be applied to your query |
| `startDateTime` | string | Only return Attendance Records that fall between the range of the `startDateTime` and `endDateTime` timestamps. Must provide `endDateTime` as well. |
| `endDateTime` | string | The end timestamp of the range to return Attendance Records within. |
| `absent` | boolean | Whether to only return Attendance Records where the student is absent (`true`) or present (`false`). |
| `explained` | boolean | Whether to only return Attendance Records where the students' absences are explained (`true`) or not explained (`false`). |
| `updatedBefore` | string | See [Updated Before or After](?id=updated-before-or-after) |
| `updatedAfter` | string | See [Updated Before or After](?id=updated-before-or-after) |
#### **Request**
```bash
curl \
--request GET \
--url 'https://api.clipboard.app/attendance-records?timePeriod=last-week&page=1&pageLength=30' \
--header 'Authorization: Bearer YOUR_TOKEN'
```
#### **Response**
```json
{
"data": [
{
"id": 3737,
"absent": false,
"explained": false,
"comment": "",
"student": {
"id": 991,
"firstName": "Pauline",
"legalFirstName": null,
"lastName": "Luna",
"smsId": "LUNA0989",
"yearGroup": {
"id": 5,
"name": "Year 11"
}
},
"session": {
"id": 158,
"title": "Hockey 1sts",
"activity": {
"id": 3,
"name": "Hockey"
},
"startDateTime": "2021-06-29T07:00:00.000Z",
"endDateTime": "2021-06-29T08:30:00.000Z"
},
"team": {
"id": 81,
"name": "1sts",
"category": {
"id": 1,
"name": "Senior"
}
},
"roll": {
"id": 264,
"timeMarked": "2021-06-29T07:00:00.000Z",
"timeEdited": null,
"markedByUser": {
"id": 4,
"firstName": "Charlotte",
"lastName": "Williams"
},
"editedByUser": null
},
"addedToRoll": false,
"updatedTimestamp": null,
"updatedByUser": null,
"attendanceFlags": [
{
"name": "Catching bus",
"id": 2
}
]
},
...
],
"pagination": {
"currentPage": 1,
"lastPage": 238,
"numRecords": 7118,
"pageLength": 30
}
}
```
## Users
### The User object
A **User** is a user of the Clipboard App (as opposed to the Portal). It is a staff member at the school.
| Attribute | Type | Description |
| ----------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `id` | number | The primary key that uniquely identifies the user in Clipboard. |
| `firstName` | string | The user's first name. |
| `lastName` | string | The user's last name. |
| `email` | string | The user's email address. |
| `mobileNumber` | string | The user's mobile number, if any. |
| `isAdmin` | boolean | If the user is an Admin. |
| `isManager` | boolean | If the user is a Manager. |
| `employeeId` | string | The user's employee ID, if any. Often corresponds to an external ID in an HR or payroll system. |
| `frozen` | `yes` \| `no` | If the user is deactivated in Clipboard. |
| `wwccNumber` | string | The user's Working With Children Check number, if any. |
| `wwccExpiryDate` | string | The timestamp of the user's WWCC expiry, if any. |
| `updatedDetails` | boolean | If the user has logged in for the first time and initially updated their details. |
| `sisId` | string \| null | **Deprecated.** The user's SIS ID. Prefer `externalId` and `secondaryExternalId`. |
| `externalId` | string \| null | The user's primary external identifier. Used by Clipboard's integrations to match a user to the system of record. |
| `secondaryExternalId` | string \| null | The user's secondary external identifier. Used when a second system of record needs its own identifier distinct from `externalId`. |
| `payment` | `ts` \| `na` | If the user's timesheets will be processed in Clipboard this will be `ts` otherwise it will be `na`. |
| `inviteEmailLastSentTimestamp` | string | The timestamp the user was last sent a welcome email with instructions on how to access Clipboard. |
| `activitiesPermissions` | object[] | List of Activities the user is assigned directly to. |
| `activityId` | number | The primary key of the Activity. |
| `activityName` | string | The name of the Activity. |
| `departments` | object[] | The Departments the user belongs to. |
| `id` | number | The primary key of the Department. |
| `name` | string | The name of the Department. |
### Get Users
Returns a list of users, filtered by the provided query parameters.
The maximum page length is 200 and the default is 100.
#### Parameters
| Parameter | Type | Description |
| ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `activityIds` | number[] | Only return users assigned to Activities with the provided IDs. |
| `departmentIds` | number[] | Only return users assigned to (or within) Departments with the provided IDs. |
| `permissionTypes` | number[] | User types enums to filter users by. `0` = Staff, `1` = Manager, `2` = Admin. |
| `frozen` | boolean | Set to `true` if you only want to return currently deactivated (formerly called "frozen") users. Set to `false` if you only want to fetch activated users. |
#### **Request**
```bash
curl \
--request GET \
--url 'https://api.clipboard.app/users?page=1&pageLength=30' \
--header 'Authorization: Bearer YOUR_TOKEN'
```
#### **Response**
```json
{
"data": [
{
"id": 39,
"email": "lillie@example.com",
"frozen": false,
"firstName": "Lillie",
"lastName": "Barrett",
"mobileNumber": null,
"isAdmin": false,
"isManager": false,
"employeeId": "LB4331",
"wwccNumber": "WWCC1272",
"wwccExpiryDate": "2021-08-07 00:00:00",
"updatedDetails": true,
"sisId": "LBARR1",
"externalId": "compass-9f8c6d8f-1b5d-4f6d-8f65-5d0f6f0d8d11",
"secondaryExternalId": "LBARR1",
"payment": "ts",
"inviteEmailLastSentTimestamp": null,
"activitiesPermissions": [
{
"activityId": 5,
"activityName": "Debating"
}
],
"departments": [
{
"id": 3,
"name": "Co-Curricular"
}
]
},
...
],
"pagination": {
"currentPage": 1,
"lastPage": 4,
"numRecords": 106,
"pageLength": 30
}
}
```
### Post Users
Provide an array of users to create for your organisation. If one of the provided users already exist in your organisation with a deactivated account, that user will be reactivated.
#### Body
The body accepts two fields.
- `users`: An array of user objects.
- `sendInviteEmail`: A boolean to toggle sending an invitation email to newly created users or not.
| Attribute | Type | Description |
| ------------------------------------------------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `users` | object[] | The list of users to create |
| `sisId` | string \| null | **Deprecated.** Prefer `externalId` and `secondaryExternalId`. Rejected with 400 if sent together with either `externalId` or `secondaryExternalId`. |
| `externalId` | string \| null | The user's primary external identifier. Rejected with 400 if `sisId` is also set on the same user object. |
| `secondaryExternalId` | string \| null | The user's secondary external identifier. Rejected with 400 if `sisId` is also set on the same user object. |
| `firstName` | string | The user's first name. |
| `lastName` | string | The user's last name. |
| `email` | string | The user's email address. |
| `userType` | admin \| manager \| staff | The user type of the user |
| `departments` | number[] | The departments the admin belongs to, provided as an array of department Ids. If the user is not an admin, provide an empty array |
| `activities` | number[] | The activities the manager or staff belong to, provided as an array of activity Ids. If the user is not a manager or staff, provide an empty array |
| `payrollId` | string \| null | The user's payrollId or employee ID, if any. Often corresponds to an external ID in an HR or payroll system. |
| `mobileNumber` | string \| null | The user's mobile number, if any. |
| `activated` | boolean | Set to `true` to create an activated user in clipboard, set to `false` to create a deactivated user. Default value is true if no value provided. |
| `payment` | `ts` \| `na` | If the user's timesheets will be processed in Clipboard this will be `ts` otherwise it will be `na`. |
| `sendInviteEmail` | boolean | Set to `true` to send an invitation email to each created user. Set to `false` to not send an invitation email. |
> **sisId backwards compatibility.** When `sisId` is set alone (without `externalId` or `secondaryExternalId`), the handler also writes the same value to `secondaryExternalId`, so the new read path returns data for legacy clients without requiring a client-side change.
#### **Request**
```bash
curl \
--request POST \
--url 'https://api.clipboard.app/users' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"users": [
{
"externalId": "501221",
"secondaryExternalId": "SB_501221",
"firstName": "Danielle",
"lastName": "Butler",
"email": "Danielle@example.com",
"userType": "admin",
"departments": [1],
"activities": [],
"payrollId": "P7777771",
"mobileNumber": "04777777777",
"activated": true,
"payment": "ts"
},
{
"sisId": "501222",
"firstName": "Jose",
"lastName": "Hinton",
"email": "Hinton@example.come",
"payrollId": "P7777772",
"mobileNumber": "0488888888",
"userType": "staff",
"departments": [],
"activities": [3],
"activated": true,
"payment": "na"
}
],
"sendInviteEmail": true
}'
```
#### **Response**
```json
{
"users": [
{
"id": 22,
"sisId": null,
"externalId": "501221",
"secondaryExternalId": "SB_501221",
"firstName": "Danielle",
"lastName": "Butler",
"email": "danielle@example.com",
"userType": "admin",
"departments": [1],
"activities": [],
"payrollId": "P7777771",
"mobileNumber": "04777777777",
"activated": true,
"payment": "ts"
},
{
"id": 23,
"sisId": "501222",
"externalId": null,
"secondaryExternalId": "501222",
"firstName": "Jose",
"lastName": "Hinton",
"email": "hinton@example.come",
"userType": "staff",
"departments": [],
"activities": [3],
"payrollId": "P7777772",
"mobileNumber": "0488888888",
"activated": true,
"payment": "na"
}
]
}
```
### Patch Users
Provide an array of existing users from your organisation to activate or deactivate, or to modify their basic details.
#### Body
The body accepts one field.
- `users`: An array of user objects. All attributes are optional and do not need to be added to the body, except the user Id.
| Attribute | Type | Description |
| ------------------------------------------------ | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `users` | object[] | The list of users to update |
| `id` | number | The primary key that uniquely identifies the user in clipboard |
| `sisId` | string \| null | **Deprecated.** Prefer `externalId` and `secondaryExternalId`. Rejected with 400 if sent together with either `externalId` or `secondaryExternalId`. Users synced by an active integration cannot update this field (422). |
| `externalId` | string \| null | The user's primary external identifier to update. Rejected with 400 if `sisId` is also set on the same user object. Users synced by an active integration cannot update this field (422). |
| `secondaryExternalId` | string \| null | The user's secondary external identifier to update. Rejected with 400 if `sisId` is also set on the same user object. Users synced by an active integration cannot update this field (422). |
| `firstName` | string | The user's first name to update. |
| `lastName` | string | The user's last name to update. |
| `email` | string | The user's email address to update. |
| `userType` | `admin`\|`manager`\|`staff` | The user type of the user to update |
| `departments` | number[] | The departments of the admin to update, provided as an array of department Ids. If the user is not an admin, provide an empty array |
| `activities` | number[] | The activities of the manager or staff to update, provided as an array of activity Ids. If the user is not a manager or staff, provide an empty array |
| `payrollId` | string \| null | The user's payrollId or employee ID to update. Often corresponds to an external ID in an HR or payroll system. |
| `mobileNumber` | string \| null | The user's mobile number to update. |
| `activated` | boolean | Set to `true` to activate/reactivate a user, set to `false` to deactivate a user. |
| `payment` | `ts` \| `na` | If the user's timesheets will be processed in Clipboard this will be `ts` otherwise it will be `na`. |
> **sisId backwards compatibility.** When `sisId` is set alone (without `externalId` or `secondaryExternalId`), the handler also writes the same value to `secondaryExternalId`, so the new read path returns data for legacy clients without requiring a client-side change.
#### **Request**
```bash
curl \
--request PATCH \
--url 'https://api.clipboard.app/users' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"users": [
{
"id": 22,
"email": "DanielleUpdated@example.com"
},
{
"id": 23,
"userType": "manager",
"departments": [],
"activities": [1, 2, 3]
},
{
"id": 10,
"activated": false
}
]
}'
```
#### **Response**
```json
{
"users": [
{
"id": 10,
"sisId": null,
"externalId": null,
"secondaryExternalId": null,
"firstName": "Cooper",
"lastName": "Jones",
"email": "Cooper@example.com",
"userType": "admin",
"departments": [1],
"activities": [],
"payrollId": "CB_01",
"mobileNumber": "+61466642069",
"activated": false,
"payment": "ts"
},
{
"id": 23,
"sisId": "501222",
"externalId": null,
"secondaryExternalId": "501222",
"firstName": "Jose",
"lastName": "Hinton",
"email": "hinton@example.come",
"userType": "manager",
"departments": [],
"activities": [2, 1, 3],
"payrollId": "P7777772",
"mobileNumber": "0488888888",
"activated": true,
"payment": "na"
},
{
"id": 22,
"sisId": null,
"externalId": "501221",
"secondaryExternalId": "SB_501221",
"firstName": "Danielle",
"lastName": "Butler",
"email": "danielleupdated@example.com",
"userType": "admin",
"departments": [1],
"activities": [],
"payrollId": "P7777771",
"mobileNumber": "04777777777",
"activated": true,
"payment": "ts"
}
]
}
```
## Incidents
### The Incident object
An **Incident** is an injury or other incident that occurs during some extracurricular activity or otherwise.
| Attribute | Type | Description |
| ------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `id` | number | The primary key that uniquely identifies the Incident in Clipboard. |
| `location` | string | The provided (text) location of the Incident. |
| `studentConcerned` | object | The student the Incident relates to, if any. |
| `id` | number | The primary key that uniquely identifies the student in Clipboard. |
| `firstName` | string | The student's first name. |
| `legalFirstName` | string \| null | The student's legal first name. |
| `lastName` | string | The student's last name. |
| `smsId` | string \| null | The student's SIS ID. |
| `yearGroup` | object | The student's current year group. |
| `id` | number | The primary key that uniquely identifies the year group in Clipboard. |
| `name` | string | The name of the year group. |
| `fields` | object \| null | The custom field values of the incident, if any. |
| `[fieldName]` | object | The name of the custom field value. |
| `value` | string | The value of the custom field. |
| `fieldType` | text \| date \| time \| photo \| dropdown \| concussion-check \| body-chart | The type of the custom field. |
| `dateTime` | string | The timestamp at which the Incident was reported. |
| `concussionStatus` | `none` \| `potential` \| `confirmed` | The concussion status of the student, if any. |
| `returnToPlay` | object \| null | The return-to-play clearance recorded for the student, if any. |
| `date` | string | The date-time the student was cleared to return to play (UTC). |
| `reason` | string \| null | The reason recorded against the return-to-play clearance. |
| `activity` | object | The Activity the Incident was for. |
| `id` | number | The primary key that uniquely identifies the Activity in Clipboard. |
| `name` | string | The name of the Activity. |
| `template` | object | The custom template this Incident follows. |
| `id` | number | The primary key that uniquely identifies the incident template in Clipboard. |
| `field` | object[] \| null | A list of the custom field templates for the incident. |
| `label` | string | The name of the custom field. |
| `fieldType` | text \| date \| time \| photo \| dropdown \| concussion-check \| body-chart | The type of the custom field. |
| `required` | boolean | Whether this custom field is required or not. |
| `limit` | number \| undefined | The character limit for text fields, if any. |
| `options` | string[] \| undefined | The options provided in a dropdown field, if any. |
| `externalField` | string | The mapping key to any external platform, such as Complispace. |
| `shift` | object | The _Session_ this Incident was for, if any. |
| `id` | number | The primary key that uniquely identifies the Session in Clipboard. |
| `title` | string \| null | The title of the Session. |
| `staffMember` | object | The _user_ (staff member) who reported this Incident. |
| `id` | number | The primary key that identifies the user in Clipboard. |
| `firstName` | string | The user's first name. |
| `lastName` | string | The user's last name. |
| `archived` | boolean | Whether the incident has been archived (`true`) or not (`false`) |
### Get Incidents
Returns a list of Incidents, filtered by the provided query parameters.
The maximum page length is 200 and the default is 100.
#### Parameters
| Parameter | Type | Description |
| ------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `activityIds` | number[] | Only return Incidents for Activities with the provided IDs. |
| `departmentIds` | number[] | Only return Incidents for Departments with the provided IDs. |
| `startDateTime` | string | Only return Incidents that are between the range of the `startDateTime` and `endDateTime` timestamps. Must provide `endDateTime` as well. |
| `endDateTime` | string | The end timestamp of the range to return Incidents within. |
| `concussionStatus` | `none` \| `potential` \| `confirmed` | The status of the Incident in terms of if the student gained a concussion. Omit to return all statuses. |
| `archived` | boolean | Only return archived (`true`) or non-archived (`false`) Incidents. Omit to return both. |
| `updatedBefore` | string | See [Updated Before or After](?id=updated-before-or-after) |
| `updatedAfter` | string | See [Updated Before or After](?id=updated-before-or-after) |
#### **Request**
```bash
curl \
--request GET \
--url 'https://api.clipboard.app/incidents?page=1&pageLength=30' \
--header 'Authorization: Bearer YOUR_TOKEN'
```
#### **Response**
```json
{
"data": [
{
"id": 10,
"location": "College Indoor Court 1",
"fields": {
"Severity": {
"value": "Moderate",
"fieldType": "dropdown"
},
"Describe what happened": {
"value": "Elbow to the head while contesting a rebound",
"fieldType": "text"
},
"Is this a potential concussion?": {
"fieldType": "concussion-check"
}
},
"dateTime": "2021-06-28T06:13:00.000Z",
"concussionStatus": "potential",
"activity": {
"id": 1,
"name": "Basketball"
},
"template": {
"id": 1,
"field": [
{
"label": "Severity",
"options": [
"Minor",
"Moderate",
"Major"
],
"required": true,
"fieldType": "dropdown"
},
{
"label": "Is this a potential concussion?",
"required": true,
"fieldType": "concussion-check"
},
{
"label": "Describe what happened",
"limit": 512,
"required": true,
"fieldType": "text",
"showLimit": true
}
]
},
"shift": {
"id": 88,
"title": "Basketball 10C/D"
},
"studentConcerned": {
"id": 695,
"firstName": "Rush",
"legalFirstName": null,
"lastName": "Anderson",
"smsId": "ANDERSON0693",
"yearGroup": {
"id": 4,
"name": "Year 10"
}
},
"staffMember": {
"id": 17,
"firstName": "Ciara",
"lastName": "Hurst"
},
"returnToPlay": {
"date": "2021-07-12T05:30:00.000Z",
"reason": "Potential concussion"
},
"archived": false
},
...
],
"pagination": {
"next": null,
"previous": null,
"currentPage": 1,
"lastPage": 1,
"numRecords": 21,
"pageLength": 30
}
}
```
## Locations
### The Location object
A **Location** represents a place or venue at which a Session or Fixture can be held (for example, a sports field, concert hall, or external venue).
| Attribute | Type | Description |
| ----------- | -------------- | ----------------------------------------------------------------------------------- |
| `id` | number | The primary key that uniquely identifies the Location in Clipboard. |
| `name` | string | The name of the Location. |
| `address` | string \| null | The address of the location, if any. |
| `latitude` | number \| null | The latitude coordinate of the location, if known. |
| `longitude` | number \| null | The longitude coordinate of the location, if known. |
| `archived` | boolean | Indicates whether the Location has been archived (true) or is still active (false). |
### Get Locations
Returns a list of Locations, filtered by the provided query parameters.
Note: currently only locations created by the Clipboard App are returned, no Association defined locations will be returned.
The maximum page length is 200 and the default is 100.
#### Parameters
| Parameter | Type | Description |
| ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `archived` | boolean | **Optional.** When set to true, returns only archived Locations; set to false, returns only active ones. If omitted, only active Locations are returned. |
#### **Request**
```bash
curl \
--request GET \
--url 'https://api.clipboard.app/locations?page=1&pageLength=50' \
--header 'Authorization: Bearer YOUR_TOKEN'
```
#### **Response**
```json
{
"data": [
{
"id": 1,
"name": "Field 1",
"address": "123 Example St, Sydney NSW 2000",
"latitude": -33.8741784,
"longitude": 151.2092767,
"archived": true
},
...
],
"pagination": {
"currentPage": 1,
"lastPage": 4,
"numRecords": 200,
"pageLength": 50
}
}
```
## Departments
### The Department object
A **department** is the overarching category that Activities fall under. Examples include Music, Co-Curricular, or Sport.
| Attribute | Type | Description |
| --------- | ------ | --------------------------------------------------------------------- |
| `id` | number | The primary key that uniquely identifies the department in Clipboard. |
| `name` | string | The department's name. |
### Get Departments
Returns a list of departments, filtered by the provided query parameters.
The maximum page length is 200 and the default is 100.
#### **Request**
```bash
curl \
--request GET \
--url 'https://api.clipboard.app/departments?page=1&pageLength=30' \
--header 'Authorization: Bearer YOUR_TOKEN'
```
#### **Response**
```json
{
"data": [
{
"id": 5,
"name": "Music",
},
...
],
"pagination": {
"currentPage": 1,
"lastPage": 4,
"numRecords": 106,
"pageLength": 30
}
}
```
## Year Groups
### The Year Group object
A **year group** is a way to organise students based on their age or the academic year they are enrolled in.
| Attribute | Type | Description |
| ---------- | ------- | --------------------------------------------------------------------- |
| `id` | number | The primary key that uniquely identifies the year group in Clipboard. |
| `name` | string | The year group's name, e.g. "Year 7". |
| `archived` | boolean | Whether the year group has been archived. |
### Get Year Groups
Returns a list of year groups. The only query parameters are page and pageLength.
The maximum page length is 200 and the default is 100.
#### **Request**
```bash
curl \
--request GET \
--url 'https://api.clipboard.app/year-groups?page=1&pageLength=30' \
--header 'Authorization: Bearer YOUR_TOKEN'
```
#### **Response**
```json
{
"data": [
{
"id": 1,
"name": "Year 7",
"archived": false
},
...
],
"pagination": {
"currentPage": 1,
"lastPage": 4,
"numRecords": 19,
"pageLength": 5
}
}
```
## Activities
### The Activity object
| Attribute | Type | Description |
| --------------------------------- | --------------------- | --------------------------------------------------------------------- |
| `id` | number | The primary key that uniquely identifies the Activity in Clipboard. |
| `name` | string | The name of the Activity. |
| `code` | string | The Payroll code of the Activity. |
| `emoji` | string | The emoji of the Activity. |
| `archived` | boolean | If the Activity has been archived. |
| `timesheetsEnabled` | boolean | If Timesheets are enabled for this Activity. |
| `hexColor` | string | The hex colour code for this Activity. |
| `smsCode` | string | The SIS code of the Activity. |
| `rollMode` | `present` \| `absent` | The default roll type of this Activity. |
| `activityType` | string | The type of the Activity. |
| `archivedByUserId` | number \| null | The ID of the user that archived the Activity. |
| `archivedTimestamp` | string \| null | The timestamp when the Activity was archived. |
| `department` | object | The department that the Activity belongs to. |
| `id` | number | The primary key that uniquely identifies the Department in Clipboard. |
| `name` | string | The name of the Department. |
### Get Activities
The maximum page length is 200 and the default is 100.
#### Parameters
| Parameter | Type | Description |
| --------------- | -------- | ------------------------------------------------------------- |
| `departmentIds` | number[] | Only return Activities for Departments with the provided IDs. |
#### **Request**
```bash
curl \
--request GET \
--url 'https://api.clipboard.app/activities?page=1&pageLength=30' \
--header 'Authorization: Bearer YOUR_TOKEN'
```
#### **Response**
```json
{
"data": [
{
"id": 1,
"name": "Basketball",
"code": "BBALL_123",
"emoji": "🏀",
"colour": 1,
"archived": false,
"timesheetsEnabled": true,
"hexColor": "54a0ff",
"hexContrastColor": "ffffff",
"accessRights": {
"moveStudentsWithoutApproval": false
},
"smsCode": "BB",
"rollMode": "present",
"activityType": "Basketball",
"defaultPayGradeId": null,
"archivedByUserId": null,
"archivedTimestamp": null,
"department": {
"id": 1,
"name": "Sport"
}
},
...
],
"pagination": {
"next": null,
"previous": null,
"currentPage": 1,
"lastPage": 1,
"numRecords": 5,
"pageLength": 100
}
}
```
## Activity Selections
### The Activity Selection object
| Attribute | Type | Description |
| ------------------------------------------------------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `id` | number | The primary key that uniquely identifies the Activity Selection in Clipboard. |
| `selectedTimestamp` | string | The timestamp when the Activity Selection was made. |
| `selectedByGuardianId` | number \| null | The ID of the guardian who made the Activity Selection. The value would be `null`, if the Activity Selection was made by a student. |
| `onWaitlist` | boolean | If the Activity Selection is on the waitlist. |
| `activity` | object | The Activity that this Selection is for. |
| `id` | number | The primary key that uniquely identifies the Activity in Clipboard. |
| `name` | string | The name of the Activity. |
| `code` | string | The Payroll code of the Activity. |
| `smsCode` | string | The SIS code of the Activity. |
| `description` | string | The description of the Activity. |
| `activityType` | string | The type of the Activity. |
| `emoji` | string | The emoji of the Activity. |
| `hexColor` | string | The hex colour code for this Activity. |
| `hexContrastColor` | string | The contrast hex colour code for this Activity. |
| `season` | object | The Selection Group which the Activity Selection belongs to. |
| `id` | number | The primary key that uniquely identifies the Selection Group in Clipboard. |
| `name` | string | The name of the Selection Group. |
| `hidden` | boolean | If the Selection Group is hidden. |
| `activitySelectionOpenTimestamp` | string \| null | The timestamp when the Selection Group is open for selections. |
| `activitySelectionCloseTimestamp` | string \| null | The timestamp when the Selection Group is closed for selections. |
| `seasonActivityOption` | object | The student who the Activity Selection is for. |
| `id` | number \| null | The primary key that uniquely identifies the option in Clipboard. |
| `label` | string \| null | Then label of the option. |
| `student` | object | The Student who the Activity Selection is for. |
| `id` | number | The primary key that uniquely identifies the student in Clipboard. |
| `smsId` | string | The student's SIS ID. |
| `firstName` | string | The student's first name. |
| `lastName` | string | The student's last name. |
| `email` | string | The student's email address. |
| `gender` | string \| null | The student's gender. |
| `yearGroup` | object | The student's current year group. |
| `id` | number | The primary key that uniquely identifies the year group in Clipboard. |
| `name` | string | The name of the year group. |
| `invoice` | object | The invoice details of this Activity Selection. |
| `id` | string | The primary key that uniquely identifies the Invoice in Clipboard. |
| `reference` | string | The reference of the Invoice. Formatted to begin with `CB-` |
| `status` | string | The current status of the Invoice. |
### Get Activity Selections
The maximum page length is 200 and the default is 100.
#### Parameters
| Parameter | Type | Description |
| ------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `activityIds` | number[] | Only return Activity Selections for Activities with the provided IDs. |
| `departmentIds` | number[] | Only return Activity Selections for Departments with the provided IDs. |
| `yearGroupIds` | number[] | Only return Activity Selections for Year Groups with the provided IDs. |
| `seasonIds` | number[] | Only return Activity Selections for Selection Groups with the provided IDs. |
| `seasonActivityOptionIds` | string[] | Only returns Activity Selections for the options with the provided IDs. |
| `selectionDateStart` | string | Only returns Activity Selections made on or after the provided date. |
| `selectionDateEnd` | string | Only returns Activity Selections made on or before the provided date. |
| `invoiceStatus` | (`unpaid` \| `paid` \| `partially-paid` \| `processing`)[] | Only returns Activity Selections whose Invoices are in the selected statuses. |
| `isDeleted` | boolean | If the Activity Selections are deleted |
#### **Request**
```bash
curl \
--request GET \
--url 'https://api.clipboard.app/activity-selections?page=1&pageLength=30' \
--header 'Authorization: Bearer YOUR_TOKEN'
```
#### **Response**
```json
{
"data": [
{
"id": 23,
"selectedTimestamp": "2022-11-23T22:51:02.064Z",
"selectedByGuardianId": null,
"onWaitlist": false,
"activity": {
"id": 5,
"name": "Debating",
"code": "DEBATING_01",
"smsCode": "DE",
"description": "",
"activityType": "Debating",
"emoji": "💬",
"hexContrastColor": "ffffff",
"hexColor": "54a0ff"
},
"season": {
"id": 2,
"name": "Term 2 2022",
"hidden": false,
"activitySelectionOpenTimestamp": null,
"activitySelectionCloseTimestamp": "2022-11-25T13:00:00.000Z"
},
"seasonActivityOption": {
"id": "43f5cd28-5dc5-4ab6-8cc7-6c072b32a117",
"label": "Tuesdays"
},
"student": {
"id": 52,
"smsId": "321052",
"firstName": "Federica",
"lastName": "Chantillon",
"email": "Federica.Chantillon@clipboard.app",
"gender": null,
"yearGroup": {
"id": 12,
"name": "Year 11"
}
},
"invoice": {
"status": "paid",
"reference": "CB-0026",
"id": "dce6be4a-4aee-422d-847d-fba11d781386"
}
},
...
],
"pagination": {
"currentPage": 1,
"lastPage": 1,
"numRecords": 15,
"pageLength": 100
}
}
```
## Pre Explained Absences
### The Student Absence object
| Attribute | Type | Description |
| ----------- | ------- | ----------------------------------------------------------------------------------------------- |
| `id` | number | The primary key that uniquely identifies the Student Absence in Clipboard. |
| `studentId` | number | The primary key that uniquely identifies the Student that this Absence applies to in Clipboard. |
| `startDate` | string | The start datetime of the Student Absence. |
| `endDate` | string | The end datetime of the Student Absence. |
| `explained` | boolean | If the absence is explained. |
| `reason` | string | The reason for the absence. |
### Get Pre Explained Absences
Returns a list of pre explained absences, filtered by the provided query parameters.
The maximum page length is 200 and the default is 100.
#### Parameters
| Parameter | Type | Description |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `studentIds` | number[] | Only return pre explained absences assigned to Students with the provided IDs. |
| `explained` | boolean | Set to `true` if you only want to return explained pre explained absences. Set to `false` if you only want to fetch unexplained pre explained absences. Exclude parameter to include both. |
| `startDateTime` | string | Only return pre explained absences that are between the range of the `startDateTime` and `endDateTime` timestamps. Must provide `endDateTime` as well. |
| `endDateTime` | string | The end timestamp of the range to return pre explained absences within. |
| `updatedBefore` | string | See [Updated Before or After](?id=updated-before-or-after) |
| `updatedAfter` | string | See [Updated Before or After](?id=updated-before-or-after) |
#### **Request**
```bash
curl \
--request GET \
--url 'https://api.clipboard.app/pre-explained-absences?page=1&pageLength=30' \
--header 'Authorization: Bearer YOUR_TOKEN'
```
#### **Response**
```json
{
"data": [
{
"id": 1,
"studentId": 123,
"startDate": "2026-03-16 00:00:00",
"endDate": "2026-03-16 23:59:59.999",
"explained": true,
"reason": "Medical appointment"
}
],
"pagination": {
"currentPage": 1,
"lastPage": 1,
"numRecords": 1,
"pageLength": 30
}
}
```
### Post Pre Explained Absences
Provide an array of pre explained absences to create for your organisation.
#### Body
The body accepts one field.
- `preExplainedAbsences`: An array of student absence objects.
| Attribute | Type | Description |
| -------------------------------------- | -------- | --------------------------------------------------------------------- |
| `preExplainedAbsences` | object[] | The list of pre explained absences to create |
| `studentId` | number | The student's Clipboard ID. |
| `startDate` | string | The start datetime of the absences. |
| `endDate` | string | The end datetime of the absences. |
| `explained` | boolean | If the absence should appear in Clipboard as explained or not. |
| `reason` | string | The reason for the absence. This will be truncated at 4096 characters |
#### **Request**
```bash
curl \
--request POST \
--url 'https://api.clipboard.app/pre-explained-absences' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"preExplainedAbsences": [
{
"studentId": 123,
"startDate": "2026-03-16T00:00:00.000Z",
"endDate": "2026-03-16T23:59:59.000Z",
"explained": true,
"reason": "Medical appointment"
}
]
}'
```
#### **Response**
```json
{
"data": [
{
"id": 1,
"studentId": 123,
"startDate": "2026-03-16 00:00:00",
"endDate": "2026-03-16 23:59:59.999",
"explained": true,
"reason": "Medical appointment"
}
]
}
```
### Patch Pre Explained Absences
Provide an array of existing pre explained absences from your organisation to activate or deactivate, or to modify their basic details.
#### Body
The body accepts one field.
- `preExplainedAbsences`: An array of student absence objects.
| Attribute | Type | Description |
| -------------------------------------- | -------- | --------------------------------------------------------------------- |
| `preExplainedAbsences` | object[] | The list of pre explained absences to create |
| `id` | number | The student absence Clipboard ID. |
| `studentId` | number | The student's Clipboard ID. |
| `startDate` | string | The start datetime of the absences. |
| `endDate` | string | The end datetime of the absences. |
| `explained` | boolean | If the absence should appear in Clipboard as explained or not. |
| `reason` | string | The reason for the absence. This will be truncated at 4096 characters |
#### **Request**
```bash
curl \
--request PATCH \
--url 'https://api.clipboard.app/pre-explained-absences' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"preExplainedAbsences": [
{
"id": 1,
"studentId": 123,
"startDate": "2026-03-17T00:00:00.000Z",
"endDate": "2026-03-17T23:59:59.000Z",
"explained": true,
"reason": "Updated reason"
}
]
}'
```
#### **Response**
```json
{
"data": [
{
"id": 1,
"studentId": 123,
"startDate": "2026-03-17 00:00:00",
"endDate": "2026-03-17 23:59:59.999",
"explained": true,
"reason": "Updated reason"
}
]
}
```
### Delete Pre Explained Absences
Delete existing pre explained absences from your organisation.
#### Body
The body accepts one field.
- `ids`: An array of student absence IDs.
| Attribute | Type | Description |
| --------- | -------- | ------------------------- |
| `ids` | number[] | The list of ids to delete |
#### **Request**
```bash
curl \
--request DELETE \
--url 'https://api.clipboard.app/pre-explained-absences' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"ids": [1, 2, 3]
}'
```
#### **Response**
```json
{}
```