Orah Open API

https://open-api-ireland.orah.com/open-api
Admin
The Orah Open API allows schools to integrate deeply with the Orah platform, providing programmatic...
Tokens:14,852
Snippets:78
Trust Score:9
Update:1 year ago
Show doc for...
Tokens:
Raw
### 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
```
Tokens:
Raw