### Get Students API Response Body Example Source: https://open-api-ireland.orah.com/open-api/index A comprehensive JSON example of the data returned by the 'Get Students' API call. It illustrates the structure of the `data` array containing multiple student objects, showcasing all their properties and nested structures like 'house'. ```json // Response Body Example: { "data": [ { "model": "student", "id": 1234, "first_name": "Joseph", "last_name": "Bloggs", "alt_name": "Joe", "birth_date": "1998-09-04", "gender": "Male", "email": "j.bloggs@example-school.nz", "home_number": "202-555-0178", "mobile_number": "+1-202-555-0192", "diet_info": "Vegetarian", "medical_info": "Penicillin allergy", "reference_id": "88372", "is_international": false, "student_type": "Boarding", "year_level": "10", "room_number": "22", "bed_number": "B", "pin_number": "6859", "photo": "https://boardingware.s3.amazonaws.com/student/photo-large/1234-u88i9e924r46xbt9-large-profile.jpg", "photo_thumbnail": "https://boardingware.s3.amazonaws.com/student/photo-thumbnail/1234-6hm4vuzhhc4pwrk9-thumbnail-profile.jpg", "deactivated": false, "deactivated_date": null, "sis_id": null, "house": { "id": 55, "sis_id": "0227" }, "created_at": "2019-11-12T00:02:59.000Z", "updated_at": "2019-11-12T00:02:59.000Z" }, { "model": "student", "id": 1235, "first_name": "Jane", "last_name": "Doww", "alt_name": "", "birth_date": "1997-06-14", "gender": "Female", "email": "j.doww@example-school.nz", "home_number": "202-555-0178", "mobile_number": "+1-202-555-0192", "diet_info": "Peanut allergy", "medical_info": "", "reference_id": "88399", "is_international": false, "student_type": "Day", "year_level": "9", "room_number": "28", "bed_number": "D", "pin_number": "9261", "photo": "https://boardingware.s3.amazonaws.com/student/photo-large/1234-u88i9e924r46xbt9-large-profile.jpg", "photo_thumbnail": "https://boardingware.s3.amazonaws.com/student/photo-thumbnail/1234-6hm4vuzhhc4pwrk9-thumbnail-profile.jpg", "deactivated": false, "deactivated_date": null, "sis_id": null, "house": null, "created_at": "2019-11-12T00:02:59.000Z", "updated_at": "2019-11-12T00:02:59.000Z" } ] } ``` -------------------------------- ### Get Location Tree: Request Body Example (JSON) Source: https://open-api-ireland.orah.com/open-api/index An example JSON payload for the 'POST /open-api/location/tree' endpoint, demonstrating how to specify the 'nested' query parameter to control the structure of the returned location data. ```JSON { "query": { "nested": false } } ``` -------------------------------- ### Get Students API Request Body Example Source: https://open-api-ireland.orah.com/open-api/index An example of the JSON request body used to call the 'Get Students' API. For a default query to retrieve all active students, an empty JSON object is typically sent. ```json // Request Body Example: {} ``` -------------------------------- ### Example Request Body for Get Roll Timeline API Source: https://open-api-ireland.orah.com/open-api/index Illustrates the JSON structure required for querying the 'Get Roll Timeline' API endpoint. It includes parameters for status, date range, page size, and page index. ```JSON { "query": { "status": "All", "date_range": { "start_date": "2020-05-01T00:00:00.000Z" }, "page_size": 50, "page_index": 0 } } ``` -------------------------------- ### Get Location Tree: Response Body Example (JSON) Source: https://open-api-ireland.orah.com/open-api/index A comprehensive JSON example of the response received from the 'POST /open-api/location/tree' endpoint, illustrating the structure of location objects, including nested child locations, and various attributes like ID, name, type, and geolocation. ```JSON { "data": [ { "model": "location", "id": 1, "name": "On Ground", "description": "Locations which are on your school campus (e.g. library), where the school has duty of care.", "address": "", "geolocation": null, "type": "zone", "state": "on_grounds", "child_locations": [ { "id": 4, "name": "English Block" }, { "id": 5, "name": "Gym" } ], "created_at": "2020-05-07T11:32:26.153Z", "updated_at": "2020-05-07T11:32:26.153Z" }, { "model": "location", "id": 2, "name": "Off Ground", "description": "Locations which are away from your school campus (e.g. museum), the school may or may not have duty of care.", "address": "", "geolocation": null, "type": "zone", "state": "off_grounds", "child_locations": [], "created_at": "2020-05-07T11:32:26.153Z", "updated_at": "2020-05-07T11:32:26.153Z" }, { "model": "location", "id": 3, "name": "Home", "description": "Locations which are away from your school campus with family or guardians and as such the school does not have duty of care.", "address": "", "geolocation": null, "type": "zone", "state": "home", "child_locations": [], "created_at": "2020-05-07T11:32:26.153Z", "updated_at": "2020-05-07T11:32:26.153Z" }, { "model": "location", "id": 4, "name": "English Block", "description": "", "address": "", "geolocation": { "lat": -53.36411749495944, "long": 126.98017977009897 }, "type": "building", "state": "on_grounds", "child_locations": [], "created_at": "2020-05-07T11:32:26.153Z", "updated_at": "2020-05-07T11:32:26.153Z" }, { "model": "location", "id": 5, "name": "Gym", "description": "", "address": "", "geolocation": { "lat": -24.584384730813696, "long": 5.656713919764144 }, "type": "outdoor_facility", "state": "on_grounds", "child_locations": [], "created_at": "2020-05-07T11:32:26.153Z", "updated_at": "2020-05-07T11:32:26.153Z" } ] } ``` -------------------------------- ### Get Current Student Location Records Request Body Example (JSON) Source: https://open-api-ireland.orah.com/open-api/index This JSON example shows the minimal request body for retrieving current student location records. It indicates that no specific parameters are required in the body for this operation. ```json {} ``` -------------------------------- ### Create Orah Leave Response Body Example Source: https://open-api-ireland.orah.com/open-api/index Example JSON structure of the response after successfully creating leave records, showing the details of the newly created leaves. ```JSON { "data": [ { "model": "leave", "id": 12345, "status": "Scheduled", "start_time": "2025-03-15T14:30:00.000Z", "end_time": "2025-03-17T18:00:00.000Z", "note": "Weekend home visit", "location": { "id": 123, "name": "Home" }, "leave_type": { "id": 42, "name": "Weekend Leave", "short_code": "WL" }, "student": { "id": 5678, "sis_id": null }, "created_at": "2025-03-10T09:45:00.000Z", "updated_at": "2025-03-15T14:30:00.000Z" }, { "id": 12346, "model": "leave", "status": "Scheduled", "start_time": "2025-03-15T14:30:00.000Z", "end_time": "2025-03-17T18:00:00.000Z", "note": "Weekend home visit", "location": { "id": 123, "name": "Home" }, "leave_type": { "id": 42, "name": "Weekend Leave", "short_code": "WL" }, "student": { "id": 5679, "sis_id": null }, "created_at": "2025-03-10T09:45:00.000Z", "updated_at": "2025-03-15T14:30:00.000Z" } ] } ``` -------------------------------- ### Get Single Orah Leave Response Body Example Source: https://open-api-ireland.orah.com/open-api/index Example JSON structure of the response when retrieving a single leave, showing all its detailed attributes. ```JSON { "data": { "model": "leave", "id": 12345, "status": "Active", "start_time": "2023-01-15T14:30:00.000Z", "end_time": "2023-01-17T18:00:00.000Z", "note": "Weekend home visit", "location": { "id": 2422, "name": "Home" }, "leave_type": { "id": 1, "name": "Weekend Leave", "short_code": "WL" }, "student": { "id": 228695, "sis_id": null }, "created_at": "2023-01-10T09:45:00.000Z", "updated_at": "2023-01-15T14:30:00.000Z" } } ``` -------------------------------- ### Example Response Body for Get Roll Timeline API Source: https://open-api-ireland.orah.com/open-api/index Shows a sample JSON response from the 'Get Roll Timeline' API, containing an array of roll objects with detailed information such as ID, type, status, student filters, dates, and creation details. ```JSON { "data": [ { "model": "roll", "id": 1336, "reference_label": "Test Roll", "type": "Daily", "mode": "manual", "status": "Complete", "roll_type_name": "Test RollType", "student_filters": { "house_filter": null, "group_filter": null, "pass_state_filter": "All" }, "start_date": "2020-06-30T00:00:00.000Z", "late_date": "2020-06-30T00:06:00.000Z", "end_date": "2020-06-30T00:12:00.000Z", "created_by": { "id": 1, "name": "Staff Test Account" }, "created_at": "2020-08-24T16:31:04.974Z", "updated_at": "2020-08-24T16:31:04.974Z" }, { "model": "roll", "id": 1337, "name": "Day Trip Bus Roll", "type": "Daily", "mode": "manual", "status": "Complete", "roll_type_name": "Day Trip", "student_filters": { "house_filter": { "id": 1, "sis_id": "100023", "name": "Example House 1" }, "group_filter": "Senior Group", "pass_state_filter": "All" }, "start_date": "2020-06-30T00:00:00.000Z", "late_date": "2020-06-30T00:02:00.000Z", "end_date": "2020-06-30T00:03:00.000Z", "created_by": { "id": 1, "name": "Jane Doe" }, "created_at": "2020-08-24T15:25:30.294Z", "updated_at": "2020-08-24T15:25:30.294Z" } ] } ``` -------------------------------- ### Create Orah Leave Request Body Example Source: https://open-api-ireland.orah.com/open-api/index Example JSON structure for creating new leave records for one or more students, specifying leave type, times, location, and notes. ```JSON { "query": { "student": { "ids": [ 5678, 5679 ], "sis_ids": [] } }, "data": { "leave_type_id": 42, "start_time": "2025-03-15T14:30:00.000Z", "end_time": "2025-03-17T18:00:00.000Z", "location_id": 123, "note": "Weekend home visit" } } ``` -------------------------------- ### Get Single Orah Leave Request Body Example Source: https://open-api-ireland.orah.com/open-api/index Example JSON structure for requesting a single leave by its Orah ID. ```JSON { "query": { "id": 12345 } } ``` -------------------------------- ### Example: Get Location Record Timeline Request Body Source: https://open-api-ireland.orah.com/open-api/index Illustrates a sample JSON request body for querying location records, including date range and pagination parameters. ```JSON { "query": { "date_range": { "start_date": "2020-05-01T00:00:00.000Z" }, "page_size": 50, "page_index": 0 } } ``` -------------------------------- ### Create New House API Endpoint Source: https://open-api-ireland.orah.com/open-api/index Details the API endpoint for creating a new 'House' entity. It provides examples of the request and response bodies, the API path, and the schemas for both request and response data. ```JSON // Request Body Example: { "data": { "name": "Example House", "sis_id": "2374980" } } ``` ```JSON // Response Body Example: { "data": { "model": "house", "id": 1234, "name": "Example House", "sis_id": "2374980", "created_at": "2019-11-12T00:02:59.000Z", "updated_at": "2019-11-12T00:02:59.000Z" } } ``` ```APIDOC POST /open-api/house/create ``` ```APIDOC Request Body: Name | Type | Description --- | --- | --- data | | Data object containing mutable attributes for the house ``` ```APIDOC Response Body: Name | Type | Description --- | --- | --- data | house | House object conforming to the house model ``` -------------------------------- ### Example: Get Location Record Timeline Response Body Source: https://open-api-ireland.orah.com/open-api/index Provides a sample JSON response body containing an array of location record objects, demonstrating the data structure returned by the API. ```JSON { "data": [ { "model": "location_record", "id": 78339, "type": "in", "record_time": "2020-05-07T11:32:25.220Z", "location": { "id": 1179, "name": "Library" }, "student": { "id": 10343, "sis_id": null }, "created_at": "2020-05-07T11:32:26.153Z", "updated_at": "2020-05-07T11:32:26.153Z" }, { "model": "location_record", "id": 78491, "type": "in", "record_time": "2020-05-07T11:38:11.193Z", "location": { "id": 1172, "name": "Gym" }, "student": { "id": 10211, "sis_id": null }, "created_at": "2020-05-07T11:38:11.788Z", "updated_at": "2020-05-07T11:38:11.788Z" } ] } ``` -------------------------------- ### Example Request Body for Get Single Roll API Source: https://open-api-ireland.orah.com/open-api/index Illustrates the JSON structure for requesting a single roll by its unique identifier (ID). ```JSON { "query": { "id": 1337 } } ``` -------------------------------- ### Example Response Body for Get Single Roll API Source: https://open-api-ireland.orah.com/open-api/index Demonstrates the detailed JSON structure returned when successfully retrieving a single roll, including its metadata, filters, dates, and associated codes and student assignments. ```JSON { "data": { "model": "roll", "id": 1337, "reference_label": "Day Trip Bus Roll", "type": "Daily", "mode": "manual", "status": "Complete", "roll_type_name": "Day Trip", "student_filters": { "house_filter": { "id": 1, "sis_id": "100023", "name": "Example House 1" }, "group_filter": "Senior Group", "pass_state_filter": "All" }, "start_date": "2020-06-30T00:00:00.000Z", "late_date": "2020-06-30T00:01:00.000Z", "end_date": "2020-06-30T00:05:00.000Z", "created_by": { "id": 1, "name": "Jane Doe" }, "created_at": "2020-06-30T00:00:00.000Z", "updated_at": "2020-06-30T00:06:00.000Z", "codes": [ { "name": "here", "type": "Present" }, { "name": "not here", "type": "Absent" } ], "student_assignments": [ { "student": { "id": 1, "sis_id": null }, "code": { "name": "not here", "type": "Absent" }, "marked_at": "2020-06-30T00:00:30.000Z", "note": "" }, { "student": { "id": 2, "sis_id": null }, "code": { "name": "here", "type": "Present" }, "marked_at": "2020-06-30T00:00:15.000Z", "note": "" } ] } } ``` -------------------------------- ### Get All Houses API Endpoint Source: https://open-api-ireland.orah.com/open-api/index Describes the API endpoint for retrieving a list of all 'House' entities. It includes examples of the request and response bodies, the API path, and the schema for the response data. ```JSON // Request Body Example: {} ``` ```JSON // Response Body Example: { "data": [ { "model": "house", "id": 1, "name": "Example House 1", "sis_id": "100023", "created_at": "2019-11-10T00:01:27.000Z", "updated_at": "2019-11-10T00:01:29.000Z" }, { "model": "house", "id": 2, "name": "Example House 2", "sis_id": "100024", "created_at": "2019-11-11T00:05:03.000Z", "updated_at": "2019-11-11T00:05:03.000Z" } ] } ``` ```APIDOC POST /open-api/house/list ``` ```APIDOC Response Body: Name | Type | Description --- | --- | --- data | house[] | Array of house objects conforming to the house model ``` -------------------------------- ### Get Current Student Location Records Response Body Example (JSON) Source: https://open-api-ireland.orah.com/open-api/index This JSON example illustrates the response structure for retrieving current student location records. It returns an array of location record objects, each containing details like type, timestamp, associated location, and student information. ```json { "data": [ { "model": "location_record", "id": 448461, "type": "in", "record_time": "2024-03-22T09:47:25.648Z", "location": { "id": 2454, "name": "Library" }, "student": { "id": 228501, "sis_id": null }, "created_at": "2024-03-22T09:47:26.053Z", "updated_at": "2024-03-22T09:47:26.053Z" }, { "model": "location_record", "id": 449751, "type": "in", "record_time": "2024-03-22T07:13:53.875Z", "location": { "id": 2422, "name": "Gym" }, "student": { "id": 228695, "sis_id": null }, "created_at": "2024-03-22T07:13:54.191Z", "updated_at": "2024-03-22T07:13:54.191Z" } ] } ``` -------------------------------- ### Example: Update Student Location Response Body Source: https://open-api-ireland.orah.com/open-api/index Provides a sample JSON response body containing updated location record objects, demonstrating the data structure returned after a successful update. ```JSON { "data": [ { "model": "location_record", "id": 78339, "type": "in", "record_time": "2023-06-27T11:32:25.220Z", "location": { "id": 9314, "name": "Library" ``` -------------------------------- ### Create New Student Record via Orah API Source: https://open-api-ireland.orah.com/open-api/index This snippet illustrates how to create a new student record using the Orah API. It provides examples of the JSON request and response payloads, as well as the API endpoint and detailed schema definitions for the data required to create a student and the structure of the successful response. ```json { "data": { "first_name": "Joseph", "last_name": "Bloggs", "alt_name": "Joe", "birth_date": "1998-09-04", "sex": "Male", "gender": "Male", "email": "j.bloggs@example-school.nz", "home_number": "202-555-0178", "mobile_number": "+1-202-555-0192", "diet_info": "Vegetarian", "medical_info": "Penicillin allergy", "reference_id": "88372", "is_international": false, "student_type": "Boarding", "year_level": "10", "room_number": "22", "bed_number": "B", "pin_number": "1234", "deactivated": false, "sis_id": null, "house": { "id": 55 } } } ``` ```json { "data": { "model": "student", "id": 1234, "first_name": "Joseph", "last_name": "Bloggs", "alt_name": "Joe", "birth_date": "1998-09-04", "gender": "Male", "email": "j.bloggs@example-school.nz", "home_number": "202-555-0178", "mobile_number": "+1-202-555-0192", "diet_info": "Vegetarian", "medical_info": "Penicillin allergy", "reference_id": "88372", "is_international": false, "student_type": "Boarding", "year_level": "10", "room_number": "22", "bed_number": "B", "pin_number": "6859", "photo": null, "photo_thumbnail": null, "deactivated": false, "deactivated_date": null, "sis_id": null, "house": { "id": 55, "sis_id": "0217" }, "created_at": "2019-11-12T00:02:59.000Z", "updated_at": "2019-11-12T00:02:59.000Z" } } ``` ```APIDOC Endpoint: POST /open-api/student/create Request Body: data (student): Data object containing mutable attributes for the student Response Body: data (student): Student object conforming to the student model ``` -------------------------------- ### Example: Update Student Location Request Body Source: https://open-api-ireland.orah.com/open-api/index Illustrates a sample JSON request body for updating student locations, specifying student IDs and the target location ID. ```JSON { "query": { "student": { "ids": [ 144266, 144267 ], "sis_ids": [] } }, "location_id": 9314 } ``` -------------------------------- ### Update Leave Response Body Example (JSON) Source: https://open-api-ireland.orah.com/open-api/index Example JSON response received after successfully updating a leave record. It includes the full details of the updated leave object, reflecting the changes made. ```JSON { "data": { "model": "leave", "id": 12345, "status": "Scheduled", "start_time": "2023-06-10T09:45:00.000Z", "end_time": "2025-03-18T16:00:00.000Z", "note": "Weekend home visit with extended end time", "location": { "id": 124, "name": "Home" }, "leave_type": { "id": 42, "name": "Weekend Leave", "short_code": "WL" }, "student": { "id": 5678, "sis_id": null }, "created_at": "2023-06-10T09:45:00.000Z", "updated_at": "2023-06-15T14:20:00.000Z" } } ``` -------------------------------- ### API: Get Contacts by Student Endpoint Source: https://open-api-ireland.orah.com/open-api/index Documents the `POST /open-api/contact/list-by-student` endpoint. This includes the specific request body parameters for querying contacts by student ID or SIS ID, the expected response structure, and example JSON payloads for both request and response. ```APIDOC Endpoint: POST /open-api/contact/list-by-student Request Body Parameters: | Name | Type | Description | | --- | --- | --- | | query | | The query object contains attributes to uniquely identify the student to get contacts by | | query > student > id | int | undefined | The Orah ID of the student to retrieve contacts for. [One of student > id or student > sis_id must be present] | | query > student > sis_id | string | undefined | The SIS ID of the student to retrieve contacts for. [One of student > id or student > sis_id must be present] | Response Body Parameters: | Name | Type | Description | | --- | --- | --- | | data | contact[] | Contact objects connected to selected student | ``` ```json { "query": { "student": { "id": 1234 } } } ``` ```json { "data": [ { "model": "contact", "id": 1432, "first_name": "Josephine", "last_name": "Bloggs", "title": "Mrs", ``` -------------------------------- ### Update Contact Request Body Example (JSON) Source: https://open-api-ireland.orah.com/open-api/index This JSON example illustrates the structure for updating an existing contact. It includes a 'query' object to identify the contact and a 'data' object with the fields to be updated, such as email and address. ```json { "query": { "sis_id": "C010258", "student": { "id": 1234 } }, "data": { "email": "j.bloggs.mum-new@example-email.com", "address": "234 Real St, Fakeville, New Zealand" } } ``` -------------------------------- ### API Endpoint for Get Roll Timeline Source: https://open-api-ireland.orah.com/open-api/index Specifies the HTTP method and path for accessing the 'Get Roll Timeline' functionality within the Orah Open API. ```APIDOC POST /open-api/roll/timeline ``` -------------------------------- ### Delete Leave Request Body Example (JSON) Source: https://open-api-ireland.orah.com/open-api/index Example JSON payload for initiating a leave record deletion. It requires only the unique identifier (ID) of the leave to be removed. ```JSON { "query": { "id": 12345 } } ``` -------------------------------- ### Get Single Orah Leave API Endpoint and Parameters Source: https://open-api-ireland.orah.com/open-api/index Documentation for the API endpoint to retrieve a single leave, including the HTTP method, path, and detailed descriptions of request and response body parameters. ```APIDOC Endpoint: POST /open-api/leave/get-single Request Body: query: object - The query object contains attributes to uniquely identify the leave to retrieve query > id: number - The Orah ID of the leave to retrieve Response Body: data: leave - Leave object conforming to the leave model ``` -------------------------------- ### Update Contact Response Body Example (JSON) Source: https://open-api-ireland.orah.com/open-api/index This JSON example shows the expected response after a successful contact update operation. It returns the full contact object with its updated attributes and metadata, including creation and update timestamps. ```json { "data": { "model": "contact", "id": 1432, "first_name": "Josephine", "last_name": "Bloggs", "title": "Mrs", "relationship": "Mother", "email": "j.bloggs.mum-new@example-email.com", "mobile_number": "+1-202-555-0159", "home_number": "202-555-0196", "address": "234 Real St, Fakeville, New Zealand", "sis_id": "C010258", "student": { "id": 1234, "sis_id": null }, "created_at": "2019-11-12T00:02:59.000Z", "updated_at": "2019-11-24T00:17:12.000Z" } } ``` -------------------------------- ### Delete Leave Response Body Example (JSON) Source: https://open-api-ireland.orah.com/open-api/index Example JSON response received after successfully deleting a leave record. Typically, a successful deletion returns an empty JSON object. ```JSON {} ``` -------------------------------- ### Update Leave Request Body Example (JSON) Source: https://open-api-ireland.orah.com/open-api/index Example JSON payload for updating an existing leave record. It specifies the unique ID of the leave to modify and the new values for fields like end time and notes. ```JSON { "query": { "id": 12345 }, "data": { "end_time": "2025-03-18T16:00:00.000Z", "note": "Weekend home visit with extended end time" } } ``` -------------------------------- ### Update Existing House API Endpoint Source: https://open-api-ireland.orah.com/open-api/index Outlines the API endpoint for modifying an existing 'House' entity. It includes examples of the request and response bodies, the API path, and the schemas for both request and response data, highlighting query parameters for identification. ```JSON // Request Body Example: { "query": { "sis_id": "2374981" }, "data": { "name": "Example Wooden House" } } ``` ```JSON // Response Body Example: { "data": { "model": "house", "id": 1234, "name": "Example Wooden House", "sis_id": "2374981", "created_at": "2019-11-12T00:02:59.000Z", "updated_at": "2019-11-13T00:05:49.000Z" } } ``` ```APIDOC POST /open-api/house/update ``` ```APIDOC Request Body: Name | Type | Description --- | --- | --- query | | The query object contains attributes to uniquely identify the house to update query > id | int | undefined | The Orah ID of the house to update. [One of id or sis_id must be present] query > sis_id | string | undefined | The SIS ID of the house to update. [One of id or sis_id must be present] data | | Data object containing mutable attributes for the house ``` ```APIDOC Response Body: Name | Type | Description --- | --- | --- data | house | House object conforming to the house model ``` -------------------------------- ### Delete Contact Response Body Example (JSON) Source: https://open-api-ireland.orah.com/open-api/index This JSON example shows the expected empty response body after a successful contact deletion, indicating the operation completed without returning specific data. ```json {} ``` -------------------------------- ### Delete Contact Request Body Example (JSON) Source: https://open-api-ireland.orah.com/open-api/index This JSON example provides the structure for the request body to delete a contact. It uses a 'query' object to specify the contact to be removed, typically by 'sis_id' or 'student' identification. ```json { "query": { "sis_id": "C010258", "student": { "id": 1234 } } } ``` -------------------------------- ### API Endpoint: Get Location Record Timeline Source: https://open-api-ireland.orah.com/open-api/index Documents the API endpoint, request, and response structures for retrieving a chronological list of student location records, including pagination and date range filtering. ```APIDOC Endpoint: POST /open-api/location-record/timeline Description: Get a list of location records ordered chronologically by record_time. This route is paginated - continue requesting pages if the number of entries returned is equal to the page size. Request Body: query (object): The query object contains attributes to filter the results student (student): Supply object to limit query for location records to one student, if not supplied query will be for all students in the school id (int): The Orah ID of the student to query, takes priority over `student > sis_id` sis_id (string): The SIS ID of the student to query date_range (object): The date range object containing the start and end date of the range to query start_date (datetime): The earliest time from which to query records (>=) - default to beginning of time if undefined end_date (datetime): The latest time from which to query records (<) - default to now if undefined page_size (int): The page size (min 1, max 1000) - defaults to 200 page_index (int): The page number, starting at zero - defaults to zero Response Body: data (location_record[]): Array of location record objects conforming to the location record model ``` -------------------------------- ### Get Pastoral Timeline API Endpoint Source: https://open-api-ireland.orah.com/open-api/index Retrieves a paginated list of pastoral entries, ordered chronologically by date. The API allows filtering by student, date range, and update time, and supports pagination. It returns a collection of detailed pastoral records. ```JSON { "query": { "date_range": { "start_date": "2020-01-01T00:00:00.000Z", "end_date": "2020-12-31T00:00:00.000Z" }, "page_size": 5, "page_index": 0 } } ``` ```JSON { "data": [ { "model": "pastoral", "id": 1, "date": "2020-02-01T05:10:53.000Z", "description": "Graffiti on wall", "action": "Made him clean it off", "note": "", "file_attachments": [ { "name": "graffiti.png" } ], "watchlist": true, "watchlist_expiry": "2020-07-04T15:28:01.606Z", "sensitive": false, "pastoral_category": { "id": 11, "name": "Discipline" }, "student": { "id": 10973, "sis_id": null }, "created_by": { "id": 1206, "name": "Jane Smith" }, "created_at": "2020-07-02T15:28:01.606Z", "updated_at": "2020-07-02T15:28:01.606Z" }, { "model": "pastoral", "id": 2, "date": "2020-04-21T14:17:45.000Z", "description": "Blood nose", "action": "Sent to nurse", "note": "", "file_attachments": [], "watchlist": false, "watchlist_expiry": null, "sensitive": false, "pastoral_category": { "id": 12, "name": "Health" }, "student": { "id": 11103, "sis_id": null }, "created_by": { "id": 1201, "name": "John Snow" }, "created_at": "2020-07-02T15:28:01.611Z", "updated_at": "2020-07-02T15:28:01.611Z" } ] } ``` ```APIDOC POST /open-api/pastoral/timeline Request Body: query: object (The query object contains attributes to filter the results) student: object (Supply object to limit query for pastoral records to one student, if not supplied query will be for all students in the school) id: int (The Orah ID of the student to query, takes priority over `student > sis_id`) sis_id: string (The SIS ID of the student to query) date_range: object (The date range object containing the start and end date of the range to query) start_date: datetime (The earliest time from which to query records (>=) - default to beginning of time if undefined) end_date: datetime (The latest time from which to query records (<) - default to now if undefined) updated_since: datetime (If provided, only records that have been created or updated since this point in time will be returned) page_size: int (The page size (min 1, max 1000) - defaults to 200) page_index: int (The page number, starting at zero - defaults to zero) nested_category: boolean (Whether the `parent_category` should be nested within `pastoral_category` if it exists) ``` -------------------------------- ### API Response Body Structure for Get Single Roll Source: https://open-api-ireland.orah.com/open-api/index Describes the structure of the response containing a single, full roll object. ```APIDOC Name: data Type: roll Description: Roll object conforming to the full roll model ``` -------------------------------- ### Delete House API Endpoint Source: https://open-api-ireland.orah.com/open-api/index Specifies the API endpoint for deleting a 'House' entity. It provides examples of the request and response bodies, the API path, and the schema for the request data, emphasizing the query parameters for identification. ```JSON // Request Body Example: { "query": { "id": 8477 } } ``` ```JSON // Response Body Example: {} ``` ```APIDOC POST /open-api/house/delete ``` ```APIDOC Request Body: Name | Type | Description --- | --- | --- query | | The query object contains attributes to uniquely identify the house to delete query > id | string | undefined | The Orah ID of the house to delete. [One of id or sis_id must be present] query > sis_id | string | undefined | The SIS ID of the house to delete. [One of id or sis_id must be present] ``` ```APIDOC Response Body: N/A ``` -------------------------------- ### Get Location Tree API Endpoint Documentation Source: https://open-api-ireland.orah.com/open-api/index Documents the 'POST /open-api/location/tree' endpoint, which retrieves the location hierarchy. It details the request body parameters, specifically the 'nested' flag to control the response structure, and the expected response body containing location data. ```APIDOC POST /open-api/location/tree Request Body: query: object description: The query object contains attributes to filter the results nested: boolean | undefined description: If true, data is returned in a full tree structure nested in child_locations. Otherwise locations are returned as a flat array, with `child_locations` only referencing direct children. Response Body: data: location[] description: A list of all locations within the school, with only the format of child_locations differing ``` -------------------------------- ### API Request Body Parameters for Get Single Roll Source: https://open-api-ireland.orah.com/open-api/index Details the parameters required in the request body to uniquely identify the roll to be retrieved. ```APIDOC Name: query Type: object Description: The query object contains attributes to uniquely identify the roll Properties: Name: id Type: int Description: The Orah ID of the roll to retrieve ``` -------------------------------- ### Get Current Student Location Records API Endpoint Source: https://open-api-ireland.orah.com/open-api/index Documents the 'POST /open-api/location-record/get-current' endpoint. This API call retrieves a list of current student location records, with one record per student, ordered by record time. ```APIDOC POST /open-api/location-record/get-current ``` -------------------------------- ### Get Students API Endpoint Specification Source: https://open-api-ireland.orah.com/open-api/index Documents the `POST /open-api/student/list` endpoint for retrieving student data. It specifies the request body parameters, such as the 'query' object with an optional 'deactivated' flag, and the expected structure of the response body, which is an array of student objects conforming to the Student Model. ```APIDOC Endpoint: POST /open-api/student/list Request Body: query: object (The query object contains attributes to uniquely identify the student) deactivated: boolean (Return a list of deactivated students - defaults to false) Response Body: data: student[] (Array of student objects conforming to the student model) ``` -------------------------------- ### Get Single Contact API Request and Response Source: https://open-api-ireland.orah.com/open-api/index Provides the JSON structure for retrieving a single contact's details, including the request payload for identification and the comprehensive response body with all contact attributes. This snippet also provides the API endpoint and schema definition. ```JSON // Request Body Example: { "query": { "id": 1432 } } ``` ```JSON // Response Body Example: { "data": { "model": "contact", "id": 1432, "first_name": "Josephine", "last_name": "Bloggs", "title": "Mrs", "relationship": "Mother", "email": "j.bloggs.mum@example-email.com", "mobile_number": "+1-202-555-0159", "home_number": "202-555-0196", "address": "345 Fake St, Fakeville, New Zealand", "sis_id": null, "student": { "id": 1234, "sis_id": null }, "created_at": "2019-11-12T00:02:59.000Z", "updated_at": "2019-11-24T00:17:12.000Z" } } ``` ```APIDOC POST /open-api/contact/get-single Request Body: query: id: int | The Orah ID of the contact to retrieve. ``` -------------------------------- ### Retrieve Single Student by ID via Orah API Source: https://open-api-ireland.orah.com/open-api/index This snippet demonstrates how to retrieve a single student record from the Orah API using their ID or SIS ID. It includes examples of the request and response JSON payloads, along with the API endpoint and schema definitions for the request and response bodies. ```json { "query": { "id": 1234 } } ``` ```json { "data": { "model": "student", "id": 1234, "first_name": "Joseph", "last_name": "Bloggs", "alt_name": "Joe", "birth_date": "1998-09-04", "gender": "Male", "email": "j.bloggs@example-school.nz", "home_number": "202-555-0178", "mobile_number": "+1-202-555-0192", "diet_info": "Vegetarian", "medical_info": "Penicillin allergy", "reference_id": "88372", "is_international": false, "student_type": "Boarding", "year_level": "10", "room_number": "22", "bed_number": "B", "pin_number": "6859", "photo": "https://boardingware.s3.amazonaws.com/student/photo-large/1234-u88i9e924r46xbt9-large-profile.jpg", "photo_thumbnail": "https://boardingware.s3.amazonaws.com/student/photo-thumbnail/1234-6hm4vuzhhc4pwrk9-thumbnail-profile.jpg", "deactivated": false, "deactivated_date": null, "sis_id": null, "house": { "id": 55, "sis_id": "0227" }, "created_at": "2019-11-12T00:02:59.000Z", "updated_at": "2019-11-12T00:02:59.000Z" } } ``` ```APIDOC Endpoint: POST /open-api/student/get-single Request Body: query: The query object contains attributes to uniquely identify the student id (int): The Orah ID of the student to retrieve. [One of id or sis_id must be present] sis_id (string): The SIS ID of the student to retrieve. [One of id or sis_id must be present] Response Body: data (student): Student object conforming to the student model ``` -------------------------------- ### Create Orah Leave API Endpoint and Parameters Source: https://open-api-ireland.orah.com/open-api/index Documentation for the API endpoint to create new leave records, including the HTTP method, path, and detailed descriptions of request body parameters. ```APIDOC Endpoint: POST /open-api/leave/create Request Body: query: object - The query object contains attributes to identify the student for the leave query > student: object - Supply object to identify the student for this leave query > student > ids: int[] - The Orah IDs of the students. [One of ids or sis_ids must be present] query > student > sis_ids: string[] - The SIS IDs of the students. [One of ids or sis_ids must be present] data: object - Data object containing attributes for the leave data > leave_type_id: int - ID of the leave type data > start_time: datetime - Start time of the leave data > end_time: datetime - End time of the leave (must be after start_time) data > location_id: int - ID of the location for the leave data > note: string - Additional notes about the leave ``` -------------------------------- ### Orah Open API Base Endpoints Source: https://open-api-ireland.orah.com/open-api/index This section lists the base URLs for accessing the Orah Open API, which vary based on the school's data center location. All connections enforce HTTPS. ```HTTP https://open-api-virginia.orah.com https://open-api-sydney.orah.com https://open-api-ireland.orah.com ``` -------------------------------- ### Orah API Type Notation Conventions Source: https://open-api-ireland.orah.com/open-api/index Explains the type notation used throughout the Orah API documentation, similar to TypeScript, covering optional parameters, nullable values, array types, and datetime format. ```APIDOC * We use a type notation similar to Typescript to describe the types of input parameters. * Types that contain union type `| undefined` do not have to be present within the request (aka optional). * Types that contain union type `| null` can explicitly set the value to null. * The notation `type[]` indications an array of responses. The type will always be an array, even if there is one element. Arrays can be empty. * `datetime` types follow the ISO date format: `YYYY-MM-DDTHH:mm:ss.sssZ` ``` -------------------------------- ### Common HTTP Status Codes for Orah API Source: https://open-api-ireland.orah.com/open-api/index Provides a comprehensive list of standard HTTP status codes returned by the Orah API, detailing their meaning and common scenarios for each error. ```APIDOC Error Code | Meaning --- | --- 400 | Bad Request -- The request could not be understood, e.g. due to incorrect request parameters or malformed request syntax. 401 | Unauthorized -- The request has not provided proper authorization, e.g. due to missing/incorrect api key or ip address not on whitelist 403 | Forbidden -- The request has been formed correctly but the api key does not have necessary permissions to access the entity 404 | Not Found -- The entity (or URL) it is trying to request cannot be found, e.g. accessing a deleted student by id 500 | Internal Server Error -- There was a problem with our server while handling the request. Try again later. 503 | Service Unavailable -- Server is temporarily offline for maintenance. Please try again later. ``` -------------------------------- ### API: General Contact Query and Response Models Source: https://open-api-ireland.orah.com/open-api/index Defines the general structure for querying contacts and the standard contact object returned in API responses. This includes parameters for uniquely identifying contacts and the structure of a single contact object. ```APIDOC General Request Body Query Parameters: | Name | Type | Description | | --- | --- | --- | | query | | The query object contains attributes to uniquely identify the contact | | query > id | int | undefined | The Orah ID of the contact to retrieve | | query > sis_id | string | undefined | The SIS ID of the contact to retrieve, if this parameter is used then at least one of `student > id`/`student > sis_id` must also be provided | | query > student > id | int | undefined | The Orah ID of the student the contact belongs to, only required if using the `sis_id` parameter | | query > student > sis_id | string | undefined | The SIS ID of the student the contact belongs to, only required if using the `sis_id` parameter | General Response Body Data Model: | Name | Type | Description | | --- | --- | --- | | data | contact | Contact object conforming to the contact model | ``` -------------------------------- ### API Endpoint: Update Student Location Source: https://open-api-ireland.orah.com/open-api/index Documents the API endpoint, request, and response structures for updating a student's current location, bypassing location-based rules. ```APIDOC Endpoint: POST /open-api/student/update-location Description: Update a student(s) current location. Behaviour is the same as updating via app, except that it bypasses any location based rules. Request Body: query (object): The query object contains attributes to filter the results student (student): Supply object to limit query for location records to specific students, if not supplied query will be for all students in the school ids (int[]): The Orah IDs of the students to query, takes priority over `student > sis_ids` sis_ids (string[]): The SIS IDs of the students to query location_id (int): The ID of the location to update the student(s) to Response Body: data (location_record[]): Array of location record objects conforming to the location record model ``` -------------------------------- ### API Schemas: Common Request and Response Structures Source: https://open-api-ireland.orah.com/open-api/index Defines common data structures used across multiple API endpoints, including the general query object for filtering and the standard response format for location records. ```APIDOC Request Body (General Query > Student): query (object): The query object contains attributes to filter the results student (student): Supply object to limit query for location records to specific students, if not supplied query will be for all students in the school ids (int[]): The Orah IDs of the students to query, takes priority over `student > sis_ids` sis_ids (string[]): The SIS IDs of the students to query Response Body (General Data Structure): data (location_record[]): Array of location record objects conforming to the location record model ``` -------------------------------- ### API Object Response Metadata Source: https://open-api-ireland.orah.com/open-api/index Object responses from the API include metadata fields. The `model` key indicates the type of object, and `created_at` and `updated_at` provide timestamps for creation and last modification. ```JSON "model": "contact", "created_at": "timestamp", "updated_at": "timestamp" ``` -------------------------------- ### Update Student API Request and Response Source: https://open-api-ireland.orah.com/open-api/index Illustrates the JSON structure for updating a student's information, including the request payload for identifying the student and the full response body with updated details. This snippet also provides the API endpoint and schema definition. ```JSON // Request Body Example: { "query": { "id": 1234 }, "data": { "alt_name": "Joey", "email": "joey.bloggs@example-school.nz", "house": { "id": 184 } } } ``` ```JSON // Response Body Example: { "data": { "model": "student", "id": 1234, "first_name": "Joseph", "last_name": "Bloggs", "alt_name": "Joey", "birth_date": "1998-09-04", "sex": "Male", "gender": "Male", "email": "joey.bloggs@example-school.nz", "home_number": "202-555-0178", "mobile_number": "+1-202-555-0192", "diet_info": "Vegetarian", "medical_info": "Penicillin allergy", "reference_id": "88372", "is_international": false, "student_type": "Boarding", "year_level": "10", "room_number": "22", "bed_number": "B", "pin_number": "1234", "photo": "https://boardingware.s3.amazonaws.com/student/photo-large/1234-u88i9e924r46xbt9-large-profile.jpg", "photo_thumbnail": "https://boardingware.s3.amazonaws.com/student/photo-thumbnail/1234-6hm4vuzhhc4pwrk9-thumbnail-profile.jpg", "deactivated": false, "deactivated_date": null, "sis_id": null, "house": { "id": 184, "sis_id": "0208" }, "created_at": "2019-11-12T00:02:59.000Z", "updated_at": "2019-11-12T00:02:59.000Z" } } ``` ```APIDOC POST /open-api/student/update Request Body: query: The query object contains attributes to uniquely identify the student to update id: int | The Orah ID of the student to update. [One of id or sis_id must be present] sis_id: string | The SIS ID of the student to update. [One of id or sis_id must be present] data: student | Data object containing mutable attributes for the student Response Body: data: student | Student object conforming to the student model ```