About
The ScholarPack REST API allows software suppliers to gain read and write access to data stored in ScholarPack schools for use in their own application.
Our Open API documentation outlines the data that can be accessed through our API. This includes for example basic student details, daily register marks, and staff details.
URI Structure
The structure of the URI to access resources is as follows:
https://<subdomain>.scholarpack.co.uk/api/<version>/<resource-name>/
<subdomain> can be either 'sandbox' or 'services'. Sandbox is the testing environment and services is the production environment.
An example URI looks like the following:
https://sandbox.scholarpack.co.uk/api/v1/students/
The current version of the ScholarPack API is 'v1'.
In order to access a resource you must send a valid access token as Bearer in the authorisation header.
Authorisation
ScholarPack uses the OAuth 2.0 authorisation code flow, or "three-legged OAuth". This protocol is widely used for enabling third-party applications to gain access to a limited scope of a resource owner's data over HTTP. Please see the authorisation section for a detailed overview.
Pagination and Filters
Pagination
To improve performance the ScholarPack REST API uses pagination. This means in a response with a large set of results the data will be spread across multiple pages to make it easier to handle. You can control the pagination by passing parameters in the request. For example by default the following request would result in the following:
GET https://sandbox.scholarpack.co.uk/api/v1/students/
{
"has_next": true,
"has_prev": false,
"next_num": 2,
"page": 1,
"pages": 8,
"per_page": 100,
"prev_num": null,
"next_uri": "https://sandbox.scholarpack.co.uk/api/v1/students/?page=2",
"prev_uri": null,
"data": [
...
]
You can for example limit the number of results per page.
GET https://sandbox.scholarpack.co.uk/api/v1/students/?per_page=100
{
"has_next": true,
"has_prev": false,
"next_num": 2,
"page": 1,
"pages": 4,
"per_page": 100,
"prev_num": null,
"next_uri": "https://sandbox.scholarpack.co.uk/api/v1/students/?page=2&per_page=100",
"prev_uri": null,
"data": [
...
]
There is a maximum allowed results per page for each endpoint. If you request greater than the maximum, the API will return the maximum allowed for that given endpoint. The maximum results per page are shown below.
| Endpoint | Maximum results per page |
| https://sandbox.scholarpack.co.uk/api/v1/students/ | 100 |
| https://sandbox.scholarpack.co.uk/api/v1/students/contacts/ | 250 |
| All other endpoints | 500 |
Filter on Fields
You can filter on any of the returned fields on all endpoints. The request format is as follows:
register/?filter=[{"field_name": "date", "operator": "=","value": "2018-01-01"}]
To filter on multiple fields, each field object can be separated by a comma:
register/?filter=[{"field_name": "date", "operator": ">","value": "2018-01-01"},
{"field_name": "date", "operator": "<","value": "2018-07-23"}]
A variety of common operators are supported:
- In a list: n
- Equal to: =
- Greater than: >
- Greater than or equal to: >=
- Less than: <
- Less than or equal to: <=
- Values not equal to: !=
Filtering on Student Admission Status
By default, all endpoints will only return information for current students. If you require information about former students, you will need to apply a filter on admission status. Admission status is a "special" field in that it is available to filter on every endpoint - whereas all other filtering can only be applied on fields returned by each endpoint.
register/?filter=[{"field_name": "admission_status", "operator": "=","value": "Former"}]
The possible values for the admission status filter are:
- Current (the default)
- Former
- Future
- Leaver
Permissions
In order for a school to authorise a client the user must have the admin role in ScholarPack.
Scopes
A list of scopes can be found here.
Rate Limiting
In order to ensure we are delivering a reliable and consistent service we have a rate limit of 700 requests per minute per integrator. We include rate limiting headers in the API response:
- X-RateLimit-Limit - The total number of requests allowed for the active window
- X-RateLimit-Remaining - The number of requests remaining in the active window
- X-RateLimit-Reset - UTC seconds since epoch when the window will be reset
- Retry-After - Seconds to retry after
If you exceed the rate limit you will receive a 429 Too Many Requests HTTP response.
Postman
Postman is a widely used tool for testing APIs.
To help you get started with the ScholarPack API we have created a Postman collection and environment. Once you have imported these into Postman and added your credentials into the environment, you will be able to test the OAuth2.0 flow and make requests.