API keys

Additional Module

The Insight API is an additional module in Insight. It allows data to be drawn out of Insight for whatever purpose the school may have.

As the API is an additional module of Insight, a separate charge applies. Please contact sales@tascsoftware.co.uk for further information.

Creating API keys

The API is managed via the API keys page. Several API keys can be configured, each of which can be used to extract a certain aspect of data from Insight.

New API keys are created using the Add button at the top of the page. An API key has the following options:

Field	Purpose
Key	This is a randomly generated string that cannot be changed
Description	The title given to the key
Role	The API key will use the chosen roles when extracting data. This may affect the data that is extracted, for example by limited the date range over which behaviour information is extracted.
IP address range	A start and end address can be set to create an IP address range. The API key will only function in this range. This is used to add security to the API
Permissions	The information that the key is allowed to extract

Using API keys

A URL is needed to extract data from Insight using the API module. The URL is constructed as follows:

https://insight.school.org/insightapi/ashx?apikey=b25a5fd2-965c-4bc8-b425-dbdc5234e6aa&op=Assignments&adno=002467

	The school's Insight URL
	The API key
	The information required from the API. The list of available information is shown in the Permission field when creating the API key
	The identifying number for the pupil

The final section of the URL is used to identify the pupil whose data is going to be extracted. In the example above, this section of the URL is &adno=002467. If the data being extracted is not specific to a student (such as PARSHousePoints) then this section can be omitted.

The example above uses ADNO to identify the pupil whose data is going to be extracted. MISID and UPN can be used instead. If this is the case, the URL would be written as:
https://insight.school.org/insightapi/ashx?apikey=b25a5fd2-965c-4bc8-b425-dbdc5234e6aa&op=Assignments&upn=N823432113104
or
https://insight.school.org/insightapi/ashx?apikey=b25a5fd2-965c-4bc8-b425-dbdc5234e6aa&op=Assignments&misid=9919

Error Messages

The following error messages can be returned by Insight to an application attempting to use Insight's API:

403.16 invalid api key
The API key used is not found in Insight

403.6 IP address rejected
The IP address that the request was sent from is not allowed

403.18 invalid operation
The operation requested by the application does not exist in Insight

403.1 Execute access is denied - role permission preclude call
The application is requesting to use an operation for which the API key does not have permission

403.13 Student id expected but none specified
An identifying number for a student is required, but has not been specified by the application