Introduction

Welcome to the Orah Open API. This API will allow you to integrate more deeply with Orah than ever before.

Changelog

16/04/25

-- Added Create, Update, and Delete Leave routes

01/04/25

• Added Leave Type and Leave models
• Added Get Leave Types route
• Added Get Single Leave route

02/04/24

• Added new route to get current student location records

27/06/23

• Added new route to update student's current location

11/08/21

• Added "student_filters" to the Roll model

01/07/21

• Rebranded to Orah
• Updated API Endpoints to orah.com domain

14/04/21

• Added "points" to the Pastoral model

05/03/21

• Get Pastoral Timeline - added "nested_category" query parameter

16/02/21

• Get Pastoral Timeline - added the "updated_since" query parameter
• Changed Pastoral model "pastoral_type" attribute to "pastoral_category"

30/11/20

• Added Student model "is_international" attribute
• Changed Student model "boarding_status" attribute to "student_type"
• Added values "Remote" and "FlexiBoarding" to "student_type"

19/08/20

• Changed Student model "ex_student" attribute to "deactivated"
• Create/Update Student routes can now set the "deactivated" value
• Deactivate/Reactivate Student routes have been removed (use update instead)
• Get Students - added a query parameter to get deactivated students

20/05/20

• Removed GET request method from use (POST only now)
• Relations are now represented as objects
• Replaced type with model in data output
• Added Location Record model and Get Location Record Timeline route

20/12/19 - Initial release

• Supports lifecycle routes for Students, Contacts and Houses.

API Endpoints

The URL to access the API depends on the datacentre your school resides in. Note: The use of HTTPS is enforced.

• https://open-api-virginia.orah.com for schools in the Americas
• https://open-api-sydney.orah.com for schools in the Asia-Pacific Region
• https://open-api-ireland.orah.com for schools in Europe, Africa and the Middle East

Authentication

Creating an API Key

As an Administrator within the Orah Admin Console, choose the settings page named "Open API". If you do not see it, please contact us to enable it for you. Within this interface you can create multiple named keys and track their lifetime and usage.

API Key usage

API requests are authorized using the generated API Key as an HTTP Request Header as follows:

Authorization : "Bearer <api-key>"

Recommended Practices

• The IP Whitelist in the API Key settings enables tighter security. We highly recommend using feature as it adds a strong second factor to the authentication chain.

• The Administration Settings for API Keys allow creation of multiple keys at once to simplify key rotation. We recommend rotating keys as often as reasonable, but at least every 6 months.

Request Conventions

• We use the POST request method for all operations, the URLs conform approximately to
  POST /open-api/namespace/action
• POST request parameters are sent as JSON data within the body of the request using the request header Content-Type: application/json
• All connections require TLS v1.2 and above (https)

Response Conventions

• Successful requests are communicated with the 200 HTTP Status Code alongside the response body
• Success or failure of request is communicated using the HTTP Status Code alongside a human readable message string in the response body - see Error Conventions
• The response body is always in JSON format, usually in the form { data: <object | array> }

Metadata

• Object responses contain a model key indicating what model that object is an instance of. eg. model: 'contact'.
• Object responses contain creation and modification timestamps in the fields created_at & updated_at, respectively.

Error Conventions

• Errors are communicated through HTTP status codes, see next section.
• Additional error details are provided in the response body as { error: { message: 'message' } }

Error HTTP Status Codes

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.

Type Notation

• 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

House

House Model

Represents a House in Orah. Students can be organised into houses.

Key	Type	Description
id	number	The Orah id
name	string	The name of the house
sis_id	string | null	Unique ID from the school's Student Information System

Get Houses

Get a list of houses

// Request Body Example:
 {}

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

POST /open-api/house/list

Request Body

N/A

Response Body

Name	Type	Description
data	house[]	Array of house objects conforming to the house model

Create House

Create a house

// Request Body Example:
 {
  "data": {
    "name": "Example House",
    "sis_id": "2374980"
  }
}

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

POST /open-api/house/create

Request Body

Name	Type	Description
data		Data object containing mutable attributes for the house

Response Body

Name	Type	Description
data	house	House object conforming to the house model

Update House

Update a house

// Request Body Example:
 {
  "query": {
    "sis_id": "2374981"
  },
  "data": {
    "name": "Example Wooden House"
  }
}

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

POST /open-api/house/update

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

Response Body

Name	Type	Description
data	house	House object conforming to the house model

Delete House

Delete a house

// Request Body Example:
 {
  "query": {
    "id": 8477
  }
}

// Response Body Example:
 {}

POST /open-api/house/delete

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]

Response Body

N/A

Student

Student Model

Represents a Student in Orah.

Key	Type	Description
id	integer	The Orah ID
first_name	string	The first name of the student
last_name	string	The surname of the student
alt_name	string	Field to store the student's preferred name
birth_date	string | null	The student's date of birth (YYYY-MM-DD)
gender	enum	'Male', 'Female', 'Other', 'Unknown'
email	string	The student's email address
home_number	string	The student's primary home phone number
mobile_number	string	The student's mobile phone number
diet_info	string	A field to store a description of any dietary requirements
medical_info	string	A field to store a description of any medical requirements
reference_id	string	The student's human-known student ID
is_international	boolean	Represents whether this student is international or not
student_type	enum	'Boarding', 'Day', 'Remote', 'FlexiBoarding'
year_level	string	Year level of the student
room_number	string	Dorm room number of the student
bed_number	string	Bed number of the student
pin_number	string	4 digit numeric code for quick access inside kiosk application
photo	url | null	URL of the large student profile picture (cannot be set via open api)
photo_thumbnail	url | null	URL of the thumbnail student profile picture (cannot be set via open api)
deactivated	boolean	Represents whether the student has been deactivated
deactivated_date	date | null	Date that the student was deactivated - null if deactivated is false (cannot be set via open api)
sis_id	string | null	Unique ID of the student from the school's Student Information System
house	object | null	The house relation that the student belongs to. (null indicates no house connection)
house > id	integer | null	Orah ID of the House that the student belongs to. (null indicates no house connection)
house > sis_id	string | null	Orah ID of the House that the student belongs to. (null indicates no house connection or sis_id not set)

Get Students

Get a list of all active (or deactivated) students

// Request Body Example:
 {}

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

POST /open-api/student/list

Request Body

Name	Type	Description
query	object | undefined	The query object contains attributes to uniquely identify the student
query > deactivated	boolean | undefined	Return a list of deactivated students - defaults to false

Response Body

Name	Type	Description
data	student[]	Array of student objects conforming to the student model

Get Single Student

Get a single student by id

// Request Body Example:
 {
  "query": {
    "id": 1234
  }
}

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

POST /open-api/student/get-single

Request Body

Name	Type	Description
query		The query object contains attributes to uniquely identify the student
query > id	int | undefined	The Orah ID of the student to retrieve. [One of id or sis_id must be present]
query > sis_id	string | undefined	The SIS ID of the student to retrieve. [One of id or sis_id must be present]

Response Body

Name	Type	Description
data	student	Student object conforming to the student model

Create Student

Create a student

// Request Body Example:
 {
  "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
    }
  }
}

// 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": 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"
  }
}

POST /open-api/student/create

Request Body

Name	Type	Description
data	student	Data object containing mutable attributes for the student

Response Body

Name	Type	Description
data	student	Student object conforming to the student model

Update Student

Update a student

// Request Body Example:
 {
  "query": {
    "id": 1234
  },
  "data": {
    "alt_name": "Joey",
    "email": "joey.bloggs@example-school.nz",
    "house": {
      "id": 184
    }
  }
}

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

POST /open-api/student/update

Request Body

Name	Type	Description
query		The query object contains attributes to uniquely identify the student to update
query > id	int | undefined	The Orah ID of the student to update. [One of id or sis_id must be present]
query > sis_id	string | undefined	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

Name	Type	Description
data	student	Student object conforming to the student model

Delete Student

Delete a student

// Request Body Example:
 {
  "query": {
    "id": 1234
  }
}

// Response Body Example:
 {}

POST /open-api/student/delete

Request Body

Name	Type	Description
query		The query object contains attributes to uniquely identify the student to delete
query > id	int | undefined	The Orah ID of the student to delete. [One of id or sis_id must be present]
query > sis_id	string | undefined	The SIS ID of the student to delete. [One of id or sis_id must be present]

Response Body

N/A

Contact

Contact Model

Represents a student's contact in Orah. Each contact belongs to exactly one student. Students can have multiple contacts

Key	Type	Description
id	int	The Orah ID
first_name	string	The first name of the contact
last_name	string	The surname of the contact
title	string	Formal title for this contact eg. Mr. Mrs.
relationship	string	A description of the relationship this contact has to student
email	string	The contact's email address
mobile_number	string	The contact's mobile phone number
home_number	string	The contact's home phone number
address	string	The contact's full address
sis_id	string	ID of the contact from the school's Student Information System. Within Orah this does not uniquely define a contact - the pair (student.sis_id, contact.sis_id) uniquely defines a contact.
student		Student that this contact belongs to
student > id	int	Orah ID of student (not editable)
student > sis_id	string | null	SIS ID of student (not editable)

Get Single Contact

Get a single contact

// Request Body Example:
 {
  "query": {
    "id": 1432
  }
}

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

POST /open-api/contact/get-single

Request Body

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

Response Body

Name	Type	Description
data	contact	Contact object conforming to the contact model

Get Contacts by Student

Get a list of contacts for a student

// Request Body Example:
 {
  "query": {
    "student": {
      "id": 1234
    }
  }
}

// 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"
    },
    {
      "model": "contact",
      "id": 1433,
      "first_name": "James",
      "last_name": "Bloggs",
      "title": "Mr",
      "relationship": "Father",
      "email": "j.bloggs.dad@example-email.com",
      "mobile_number": "+1-202-555-0147",
      "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:13.000Z"
    }
  ]
}

POST /open-api/contact/list-by-student

Request Body

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

Name	Type	Description
data	contact[]	Contact objects connected to selected student

Create Contact

Create a contact

// Request Body Example:
 {
  "data": {
    "student": {
      "id": 1234
    },
    "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": "123 Fake St, Fakeville, New Zealand",
    "sis_id": null
  }
}

// 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": "123 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-12T00:02:59.000Z"
  }
}

POST /open-api/contact/create

Request Body

Name	Type	Description
data	contact	Data object containing mutable attributes for the contact
Relations:
data > student > id	int | undefined	The Orah ID of the student the contact belongs to
data > student > sis_id	string | undefined	The SIS ID of the student the contact belongs to

Response Body

Name	Type	Description
data	contact	Contact object conforming to the contact model

Update Contact

Update a contact

// Request Body Example:
 {
  "query": {
    "sis_id": "C010258",
    "student": {
      "id": 1234
    }
  },
  "data": {
    "email": "j.bloggs.mum-new@example-email.com",
    "address": "234 Real St, Fakeville, New Zealand"
  }
}

// Response Body Example:
 {
  "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"
  }
}

POST /open-api/contact/update

Request Body

Name	Type	Description
query		The query object contains attributes to uniquely identify the contact to update
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	object | undefined	The student object contains attributes to identify the student the contact belongs to
query > student > id	int | undefined	The Orah ID of the student the contact belongs to
query > student > sis_id	string | undefined	The SIS ID of the student the contact belongs to, only required if using the `sis_id` parameter
data	contact	Data object containing mutable attributes for the contact

Response Body

Name	Type	Description
data	contact	Contact object after update operation

Delete Contact

Delete a contact

// Request Body Example:
 {
  "query": {
    "sis_id": "C010258",
    "student": {
      "id": 1234
    }
  }
}

// Response Body Example:
 {}

POST /open-api/contact/delete

Request Body

Name	Type	Description
query		The query object contains attributes to uniquely identify the contact to delete
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	object | undefined	The student object contains attributes to identify the student the contact belongs to
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

Response Body

N/A

Location Record

Location Record Model

Represents a Location Record object in Orah.

Key	Type	Description
id	integer	The Orah ID
type	enum	The type of location record: 'in' (check in record), 'transit' (in transit record)
record_time	datetime	The timestamp of the location record
location		The related location object
location > id	integer	The ID of the location
location > name	string	The name of the location
student		The related student object
student > id	integer	The ID of the student
student > sis_id	string | null	The SIS ID of the student

Get Current Student Location Records

Get a list of current student location records at the present moment in time. One location record will be returned per student. However, it is possible for a newly created student to not yet have a location record. The list is in reverse chronological order by record_time.

// Request Body Example:
 {}

// Response Body Example:
 {
  "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"
    }
  ]
}

POST /open-api/location-record/get-current

Request Body

Name	Type	Description
query	object | undefined	The query object contains attributes to filter the results
query > student	student | undefined	Supply object to limit query for location records to specific students, if not supplied query will be for all students in the school
query > student > ids	int[] | undefined	The Orah IDs of the students to query, takes priority over `student > sis_ids`
query > student > sis_ids	string[] | undefined	The SIS IDs of the students to query

Response Body

Name	Type	Description
data	location_record[]	Array of location record objects conforming to the location record model

Get Location Record Timeline

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 Example:
 {
  "query": {
    "date_range": {
      "start_date": "2020-05-01T00:00:00.000Z"
    },
    "page_size": 50,
    "page_index": 0
  }
}

// Response Body Example:
 {
  "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"
    }
  ]
}

POST /open-api/location-record/timeline

Request Body

Name	Type	Description
query		The query object contains attributes to filter the results
query > student	student | undefined	Supply object to limit query for location records to one student, if not supplied query will be for all students in the school
query > student > id	int | undefined	The Orah ID of the student to query, takes priority over `student > sis_id`
query > student > sis_id	string | undefined	The SIS ID of the student to query
query > date_range	object | undefined	The date range object containing the start and end date of the range to query
query > date_range > start_date	datetime | undefined	The earliest time from which to query records (>=) - default to beginning of time if undefined
query > date_range > end_date	datetime | undefined	The latest time from which to query records (<) - default to now if undefined
query > page_size	int | undefined	The page size (min 1, max 1000) - defaults to 200
query > page_index	int | undefined	The page number, starting at zero - defaults to zero

Response Body

Name	Type	Description
data	location_record[]	Array of location record objects conforming to the location record model

Update Student Location

Update a student(s) current location. Behaviour is the same as updating via app, except that it bypasses any location based rules.

// Request Body Example:
 {
  "query": {
    "student": {
      "ids": [
        144266,
        144267
      ],
      "sis_ids": []
    }
  },
  "location_id": 9314
}

// Response Body Example:
 {
  "data": [
    {
      "model": "location_record",
      "id": 78339,
      "type": "in",
      "record_time": "2023-06-27T11:32:25.220Z",
      "location": {
        "id": 9314,
        "name": "Library"
      },
      "student": {
        "id": 144266,
        "sis_id": null
      },
      "created_at": "2023-06-27T11:32:26.153Z",
      "updated_at": "2023-06-27T11:32:26.153Z"
    },
    {
      "model": "location_record",
      "id": 78340,
      "type": "in",
      "record_time": "2023-06-27T11:38:11.193Z",
      "location": {
        "id": 9314,
        "name": "Library"
      },
      "student": {
        "id": 144267,
        "sis_id": null
      },
      "created_at": "2023-06-27T11:38:11.788Z",
      "updated_at": "2023-06-27T11:38:11.788Z"
    }
  ]
}

POST /open-api/student/update-location

Request Body

Name	Type	Description
query		The query object contains attributes to identify the students to update
query > student	student	Supply object to limit query for list of students
query > student > ids	int[] | undefined	The Orah IDs of the students to update. [One of ids or sis_ids must be present]
query > student > sis_ids	string[] | undefined	The SIS IDs of the students to update. [One of ids or sis_ids must be present]
location_id	int	The Orah ID of the location to set as the students current location

Response Body

Name	Type	Description
data	location_record[]	Array of location record objects conforming to the location record model

Location

Location Model

Represents a Location element in Orah. Locations are organised in a tree-structure, with child locations inheriting certain rules from parent locations.

Key	Type	Description
id	integer	The Orah ID
name	string
description	string	A description of the of the location
address	string	An address for location, if relevant
geolocation	geolocation | null	An geolocation in the format { lat: number, long: number }
type	enum	The type of location: 'zone', 'building', 'room', 'floor', 'residential_building', 'general', 'outdoor_facility'. 'Zone' is a special location type that can only be at the root of the location tree.
state	enum	'on_grounds', 'off_grounds', 'home'
child_locations	location[]	The child location objects, can be represented as a nested structure or as a reference relation by id

Get Location Tree

// Request Body Example:
 {
  "query": {
    "nested": false
  }
}

// Response Body Example:
 {
  "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"
    }
  ]
}

POST /open-api/location/tree

Request Body

Name	Type	Description
query		The query object contains attributes to filter the results
query > nested	boolean | undefined	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

Name	Type	Description
data	location[]	A list of all locations within the school, with only the format of child_locations differing

Pastoral

Pastoral Model

Pastoral objects represent student-related events created by school staff. This includes such things as discipline, merit and health events.

Key	Type	Description
id	number	The Orah ID
date	date	The date and time of the incident
description	string	Text input into `description` field by the staff user
action	string	Text input into `action` field by the staff user
note	string	Text input into `note` field by the staff user
file_attachments	file_attachment[]	Array of file attachment objects containing the file name
watchlist	boolean	Whether the student has been flagged for this incident
watchlist_expiry	date | null	Time that watchlist status will automatically expire
sensitive	boolean	If entry is `sensitive` only staff members with extra privileges will be able to view this entry
points	number | null	The number of points assigned to the pastoral record, if points were not explicitly assigned then this value is null
pastoral_category		The related pastoral_category object
pastoral_category > id	integer	The ID of the pastoral_category
pastoral_category > name	string	The name of the pastoral_category
student		The related student object
student > id	integer	The ID of the student
student > sis_id	string | null	The SIS ID of the student
created_by		The related staff object that created the pastoral entry
created_by > id	integer	The ID of the staff object
created_by > name	string	The full name of the staff member

Get Pastoral Timeline

Get a list of pastoral entries ordered chronologically by date. This route is paginated - continue requesting pages if the number of entries returned is equal to the page size.

// Request Body Example:
 {
  "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
  }
}

// Response Body Example:
 {
  "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"
    }
  ]
}

POST /open-api/pastoral/timeline

Request Body

Name	Type	Description
query		The query object contains attributes to filter the results
query > student	student | undefined	Supply object to limit query for pastoral records to one student, if not supplied query will be for all students in the school
query > student > id	int | undefined	The Orah ID of the student to query, takes priority over `student > sis_id`
query > student > sis_id	string | undefined	The SIS ID of the student to query
query > date_range	object | undefined	The date range object containing the start and end date of the range to query
query > date_range > start_date	datetime | undefined	The earliest time from which to query records (>=) - default to beginning of time if undefined
query > date_range > end_date	datetime | undefined	The latest time from which to query records (<) - default to now if undefined
query > updated_since	datetime | undefined	If provided, only records that have been created or updated since this point in time will be returned
query > page_size	int | undefined	The page size (min 1, max 1000) - defaults to 200
query > page_index	int | undefined	The page number, starting at zero - defaults to zero
query > nested_category	boolean | undefined	Whether the `parent_category` should be nested within `pastoral_category` if it exists

Response Body

Name	Type	Description
data	pastoral[]	Array of pastoral objects conforming to the pastoral model

Roll

Roll Model

Exposes completed rolls generated within Orah. Can be manual rolls, automatic rolls or emergency rolls.

Key	Type	Description
id	number	The Orah ID
reference_label	string	Given reference label of this roll
type	enum	The core type of roll taken: 'Daily', 'Emergency'
mode	enum	The mechanism by which the roll was taken, by staff members or scheduled by the system based on location records: 'manual', 'automatic'
status	enum	The life-cycle status of the roll, either ongoing or completed: 'Active', 'Complete'
roll_type_name	string	The name of the Roll Type this roll is an instance of
student_filters	object	Student filters applied to roll at time of roll creation
student_filters > house_filter	object | null	House relation object, `null` if no house filter applied
student_filters > group_filter	string | null	Group name, `null` if no house filter applied
student_filters > pass_state_filter	enum	The current pass state of students: 'All', 'In', 'Out'
start_date	date	The timestamp that the roll was started
late_date	date | undefined	The timestamp representing a late arrival
end_date	date | undefined	The timestamp representing an absence
created_by	object | undefined	The related staff object that created the roll entry, unless the roll is of 'automatic' type
created_by > id	integer	The ID of the staff object
created_by > name	string	The full name of the staff member
codes	object[]	The list of possible codings applied to students during this roll
codes > name	string	The user-facing name for this roll code, can be customised in Roll Type interface. Default options are: 'Present', 'Late', 'Absent'
codes > type	enum	The semantic type of the code: 'Present', 'Explained Absence', 'Absent', 'Unmarked'
student_assignments	object[]	The array of student-status objects representing the results of the roll, only available using the `get-single` API route
student_assignments > student	object	The student relation for this recorded roll state
student_assignments > student > id	integer	The ID of the student
student_assignments > student > sis_id	string | null	The SIS ID of the student
student_assignments > code > name	string	The user-facing name for the roll code assigned to this student. From the array `codes` in the parent object.
student_assignments > code > type	enum	The semantic type of the code assigned to this student. From the array `codes` in the parent object.
student_assignments > marked_at	Date | null	The timestamp when this student was marked
student_assignments > note	string	An note that the staff member could have entered at the time of the roll

Get Roll Timeline

Get all rolls between the queried dates. Option to filter by roll status.

// Request Body Example:
 {
  "query": {
    "status": "All",
    "date_range": {
      "start_date": "2020-05-01T00:00:00.000Z"
    },
    "page_size": 50,
    "page_index": 0
  }
}

// Response Body Example:
 {
  "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"
    }
  ]
}

POST /open-api/roll/timeline

Request Body

Name	Type	Description
query		The query object contains attributes to filter the results
query > status	enum | undefined	'Complete', 'Active', 'All': Filter rolls returned based on their life-cycle status. Defaults to 'Complete' if parameter omitted
query > date_range	object | undefined	The date range object containing the start and end date of the range to query
query > date_range > start_date	datetime | undefined	The earliest time from which to query records (>=) - default to beginning of time if undefined
query > date_range > end_date	datetime | undefined	The latest time from which to query records (<) - default to now if undefined
query > page_size	int | undefined	The page size (min 1, max 1000) - defaults to 200
query > page_index	int | undefined	The page number, starting at zero - defaults to zero

Response Body

Name	Type	Description
data	roll[]	List of Roll objects within the specified query range. The fields `codes` and `student_assignments` are not populated by this endpoint

Get Single Roll

Get a single roll, used to get the entire roll contents.

// Request Body Example:
 {
  "query": {
    "id": 1337
  }
}

// Response Body Example:
 {
  "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": ""
      }
    ]
  }
}

POST /open-api/roll/get-single

Request Body

Name	Type	Description
query		The query object contains attributes to uniquely identify the roll
query > id	int | undefined	The Orah ID of the roll to retrieve

Response Body

Name	Type	Description
data	roll	Roll object conforming to the full roll model

Leave Type

Leave Type Model

Represents a Leave Type in Orah. Leave Types define different kinds of absences.

Key	Type	Description
id	number	The Orah ID
name	string	The name of the leave type
short_code	string	The short code assigned to the leave type
description	string	Description of the leave type

Get Leave Types

Get a list of active leave types

// Request Body Example:
 {}

// Response Body Example:
 {
  "data": [
    {
      "model": "leave_type",
      "id": 1,
      "name": "Weekend Leave",
      "short_code": "WL",
      "description": "Standard weekend leave",
      "created_at": "2019-11-10T00:01:27.000Z",
      "updated_at": "2019-11-10T00:01:29.000Z"
    },
    {
      "model": "leave_type",
      "id": 2,
      "name": "Sports Event",
      "short_code": "SE",
      "description": "School sports event",
      "created_at": "2019-11-11T00:05:03.000Z",
      "updated_at": "2019-11-11T00:05:03.000Z"
    }
  ]
}

POST /open-api/leave-type/list

Request Body

N/A

Response Body

Name	Type	Description
data	leave_type[]	Array of leave type objects conforming to the leave type model

Leave

Leave Model

Represents a Leave in Orah. Leaves represent periods of time when students are excused or absent.

Key	Type	Description
id	number	The Orah ID
status	enum	Status of the leave: 'Scheduled', 'Cancelled', 'Active', 'Past'
start_time	datetime | null	Start date and time of leave
end_time	datetime | null	End date and time of leave
note	string	Additional notes about the leave
location	object | null	The related location object
location > id	integer	The ID of the location
location > name	string	The name of the location
leave_type	object | null	The related leave type object
leave_type > id	integer	The ID of the leave type
leave_type > name	string	The name of the leave type
leave_type > short_code	string	The short code of the leave type
student	object	The related student object
student > id	integer	The ID of the student
student > sis_id	string | null	The SIS ID of the student

Get Single Leave

Get a single leave by ID

// Request Body Example:
 {
  "query": {
    "id": 12345
  }
}

// Response Body Example:
 {
  "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"
  }
}

POST /open-api/leave/get-single

Request Body

Name	Type	Description
query		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

Name	Type	Description
data	leave	Leave object conforming to the leave model

Create Leave

Create new leave records for one or more students. The status of the leave is determined by the start and end times. If the start time is in the future, the leave is "Scheduled". If the start time has passed, and the end time is in the future, the leave is "Active". If the end time has passed, the leave is "Past".

// Request Body Example:
 {
  "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"
  }
}

// Response Body Example:
 {
  "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"
    }
  ]
}

POST /open-api/leave/create

Request Body

Name	Type	Description
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[] | undefined	The Orah IDs of the students. [One of ids or sis_ids must be present]
query > student > sis_ids	string[] | undefined	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 | undefined	ID of the location for the leave
data > note	string | undefined	Additional notes about the leave

Response Body

Name	Type	Description
data	leave[]	Array of leave objects conforming to the leave model

Update Leave

Update an existing leave record. This allows modification of start time, end time, location, and note.

// Request Body Example:
 {
  "query": {
    "id": 12345
  },
  "data": {
    "end_time": "2025-03-18T16:00:00.000Z",
    "note": "Weekend home visit with extended end time"
  }
}

// Response Body Example:
 {
  "data": {
    "model": "leave",
    "id": 12345,
    "status": "Scheduled",
    "start_time": "2025-03-15T14:30: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"
  }
}

POST /open-api/leave/update

Request Body

Name	Type	Description
query	object	The query object contains attributes to uniquely identify the leave to update
query > id	number	The Orah ID of the leave to update
data	object	Data object containing attributes to update
data > start_time	datetime | undefined	New start time for the leave
data > end_time	datetime | undefined	New end time for the leave
data > location_id	int | undefined	ID of the new location for the leave
data > note	string | undefined	New note about the leave
data > comment	string | undefined	Comment about the edit to the leave

Response Body

Name	Type	Description
data	leave	Updated leave object conforming to the leave model

Delete Leave

Delete a leave record.

// Request Body Example:
 {
  "query": {
    "id": 12345
  }
}

// Response Body Example:
 {}

POST /open-api/leave/delete

Request Body

Name	Type	Description
query		The query object contains attributes to uniquely identify the leave to delete
query > id	number	The Orah ID of the leave to delete

Response Body

N/A