APIs

The INTO API follows the basic Representational State Transfer (REST) protocol as explained here

The REST API endpoints are distributed using the Azure API Management facility hosted and provided by Microsoft.com

Access to our full API catalog is available via our secure API Gateway

The following API Products exist in both environments.  Products are categories of APIs of varying sophistication available to different development partners.

Once subscribed - developers will have access to the API portal. Under the Profile section, you will be able to establish your Primary key that identifies and authenticates developers onto the API. This is key must be kept safe and not disclosed.

The APIs available at the time of writing perform the following basic business functions

• Querying of the INTO Product (Course) catalog and related objects
• Creation of an Account (Lead) object through APIs
• Updating of created record objects through APIs
• Searching of the INTO Product Catalog

The API Gateway provides a very comprehensive list of the available API's and also offers a "Try It" function.  The option to generate code stubs in multiple languages is also available.

Detailed coding and reference data with sample calls are available in the Reference Library area of this site 

This Reference Library includes a full breakdown of the Search Catalogs, Affiliate API Sample Payloads along with examples of the live and test (UAT) URLs

INTO’s affiliate partners that want to generate leads for INTO for prospective applications have access to a suite of APIs that allow for the searching and listing of INTO’s product set, it also allows for the application of a lead using the Apply API.

The searching and listing (catalog) APIs for INTO’s affiliate partners can be used in a number of ways, for the population of the affiliate’s own systems, automatic creation of applications (Apply), or for populating the affiliates own websites and other recruitment material.

The examples and payloads on this site describe the requirements and outputs of the APIs in the affiliate suite and make use of the Developer Portal on the INTO API Gateway to aid in the quick testing and development of integrations.

INTO have also created a ‘Search and Apply Widget’ which utilises the API set to provide a ready to use course listing, searching and application product which can quickly and easily be customised and added to sites and systems with very little effort.

The Search API can be used to search for outcomes and progressions via multiple fields, such as SubjectSearchPhrase. 

• Select API: Search
• Select operation: Returns courses matching the search criteria 
• For example, keeping with the earlier examples, enter query parameters: 
• For example -  In UniNames enter "City, University of London" 
• For example DirectEntry enter false 

This will return outcomes at the given university, but exclude Direct Entry courses. An example outcome is shown below. The id and progressionId fields are the outcome and progression ids needed by the Apply API. 

The Developer Portal can assist users by helping to build a call, issue it and view results. 

Return to the Developer Portal and login 

1. Select the Products tab, then the Affiliate product 
2. Select API: Apply 
3. Select operation: Create a new student, complete with applications, etc if present 
4. The portal will show documentation about the operation, such as a description, the URL format, parameters, response body format and code examples of calling the operation 
5. Click the Try It button 
6. Enter the payload into the Request Body field. An example is shown below 
7. The Ocp-Apim-Subscription-Key header is added automatically by the Developer Portal. When calling the API from your own code you will need to add this header and key value 
8. Click Send. The results of the call will be displayed once the call completes. In this example you should receive a 201 Created status. 

The API supports many optional fields. In this example only some key fields are shown. Refer to the API documentation for more details.

Country codes are specified in ISO 3166-1 alpha-2 format.

This API call requires an Outcome Id (courseId) found in applications.programInformation. These values can be found with the Catalog and/or Search APIs.

You can retrieve a list of INTO Centres using the following approach

• Select API: Catalog API v1.0 

• Enter name,slug in the field: fields 

This will fetch a list of the universities and the slugs needed for the following call, as per the following example output. 

1. Select API: Catalog API v1.0 
2. Select operation: Return outcomes by university id… 
3. Enter a slug from the call above into universitySlug. For example: city-university-london 
4. Enter field names into fields, to reduce the result payload. For example: name,outcomeLevel,slug,id 
5. This will return the outcomes available at a single university. The id is the Outcome Id that should be supplied to the Apply API’s courseId 

1. Select API: Catalog API v1.0 
2. Select operation: Returns a list of progression options for a given outcome by outcome id 
3. Enter an outcome id, returned by the previous call for example, into the id field. For example: aCI3A000000CabvWAC
4. This will return the progressions available for the given outcome. The progression.id field (in bold) is the Progression Id that should be supplied to the Enrollment API’s progressionCourseId 

Partners that wish to take advantage of INTO’s Direct Entry offering have access to a specific suite of APIs that allow for the monitoring of a student/application status, limited updates to student details back to INTO, and the ability to download documents that are related to the student directly through the API

These APIs allow for the Direct Entry partner to query and synchronise the details that INTO currently holds with their own system(s) and to correct or update details such as an external student number or email address back to INTO where required.

The ability to download and store and check documents is also included and the method to identify and download the attachments is described fully in the section named 'Downloading Attached Document Files'

Direct Entry - Summary of API's

All calls that are made to the Direct Entry APIs require that an authorisation token is requested and supplied in order that the requests are successfully routed to INTO’s student systems securely, the method is described in the ‘Making a call to authenticate’ section of this site. In the example in this section the partner is using the Developer Portal in the INTO API Gateway, however the method is the same regardless of how the API is called

The Direct Entry data model is built around the concept of an INTO Application, which is a relationship between: 

• A student 
• A partner university (or INTO Centre) 

• One or more courses. These are the course(s) being applied for by the student at the partner/centre. These are referred to as Courses Applied For (CAFs) 
• Zero or more documents  

There are many scenarios which involve multiple CAFs, such as: 

• The student may contact INTO to change the course that was originally applied for, before the application is sent to the partner. 

• The student may contact the partner university to change the course being applied for, after the application has been transferred to the partner. 
• The partner university may decide the student isn’t eligible for the requested course, then offer them an alternative. 

The Developer Portal documents the APIs and can make test API calls. 

1. Return to the Developer Portal and login 
2. Select the Products tab, then the Direct Entry product 
3. Select the API, such as Direct Entry Partners API 2.0 
4. Select an operation, such as Get authorization token 
5. The portal will show documentation about the operation, such as a description, the URL format, parameters, response body format and code examples of calling the operation 
6. Click the Try It button 
7. Enter query parameters, such as the API version required (2.0 for example) 
8. The Ocp-Apim-Subscription-Key header is added automatically by the Developer Portal. When calling the API from your own code you will need to add the header and key value 
9. In the request body, supply the username and password issued to you by INTO  
10. Click Send. The results of the call will be displayed once the call completes 

The accessToken value returned by this call must be attached as an HTTP Authorization (Bearer token) header to all other calls to this API. 

Each access token is valid for 1 day. The expected usage is that an integration will be scheduled to run periodically (every hour for example) and will request a new access token when it initialises which is then reused for all API calls during that run of the integration. 

Making other calls to the API is similar to the authentication call outlined above, except the accessToken received from the authentication call must be added as an HTTP Authorization (Bearer token) header. If this is missing or invalid the call will respond with the 401 Unauthorized status. 

The header value should be the keyword “Bearer” followed by the token, separated by a space

The partner will need to call the API periodically, to get new and updated application data, and process it, as outlined in the following logical order: 

• Call API to get applications changed since last time 

For each application: 

• Lookup the INTO application id in the partner’s system 
• If the Id is not found 
• The application is new: add it to partner system 
• Otherwise 
• The application is updated: update it in partner system (see Data Updates below) 

INTO Applications that were previously manually transferred (manually keyed into the partner system) may be reconciled with the application.IntoId (IN:E1234567Q for example). 

However, the application.Id field (XXXXXXXXXXXXXXXXXX for example) is the one that will be needed to make application updates back to the API, so will also need to be stored by the partner.

The API allows some limited application data to be returned from the partner to INTO, via the Update Application operation, such as a student number and email address which may have been generated by the partner on behalf of the student. 

Student details received from the API may represent students that are already present in the partner’s systems, in which case the partner may need to de-duplicate the student in line with their usual practices. 

Documents are never updated in INTO’s systems, they can only be added and deleted, so a partner’s interface need only store and compare document Ids to decide if a document is new or deleted. It should not be necessary to compare the document file’s contents. 

The application data contains a list of documents attached to the application. Each entry contains the document’s Attachment ID. 

Users can call the SFDocument API to download an attached file using an Attachment ID. 

Users first need to obtain a Salesforce authentication token from the Direct Entry API. This is a different token from the one we obtained earlier. 

Call the Get document download token operation to obtain a Salesforce authentication token. As before, you will need to supply the API version and Authorization token. 

The token will be returned in the response body in the authenticationToken field. 

Use the SFDocument API to download the file. 

Add the Attachment ID from the application data to the fileid query parameter. 

Add an Authorization header. Set the value to be Bearer followed by the Salesforce authentication token from the previous step, separated by a space. 

The Developer Portal will not launch a file download, but will show the content type and will render the file contents as text. 

To inform INTO of a partner’s decisions or a student’s responses the partner will need to store INTO’s Course Applied For (CAF) Ids for return via the API’s Update Course operation. 

When a student is changing course or deferring the course to a later start then the partner must update the existing CAF (as above) with the relevant decision status. They must then call the Add Course operation to generate a CAF for the new course. The API will return a new CAF that the partner must store, so future decisions and responses for the new CAF can be sent. 

The partner may call the API for updated applications as often as needed (hourly for example). 

Overlapping the update windows, by requesting changes in the previous 24 hours, but calling every hour for example, will result in the same applications being returned multiple times and therefore being reprocessed unnecessarily by the partner. 

The API permits this to allow the partner to easily recover from periods of outage or to reprocess applications if the partner’s processing needs are altered. 

On the other hand, some overlap is recommended in order to prevent application changes being missed due to slipped polling schedules. 

The API may cache results and/or use rate and bandwidth limits to mitigate overly aggressive call volumes.

The API will only allow access to applications that are for the calling partner. 

The API will only allow access to applications that are relevant to Direct Entry. Applications that were made via the Partner Portal, for example. 

The API will only allow access to applications once they have been accepted and evaluated by INTO and marked to indicate that they are ready to be made available via the API. 

The Get Applications operation will only include applications which have changed at INTO during the requested time period. 

Only fields that are exposed through the API are considered when looking for changes. INTO’s systems may contain data which is not exposed via the API: changes to that data will be ignored by the API. 

Changes to related entities, such as Prior Qualifications, Courses, Documents, etc will be considered to mean the application has changed. So, if a new document is added to an application, for example, then that application will reappear in the Get Applications operation. 

The API does not indicate whether an application is new or updated. An interfacing system would need to store the API’s ids and look them back up to determine this. 

The API does not indicate which field(s) or related object(s) have changed. That is, it does not supply a list of change deltas. The partner will need to compare the current API field values with those seen previously, such as those in their own system, to determine this. In many cases the partner may not be interested in changes to data made by INTO and may elect to ignore the change. 

Given that an application may appear in the results multiple times (see the discussion about overlapping polling intervals, above, for example) the partner’s interface should compare the current API values with the previously seen values, such as those stored in the partner system, to decide if an update has occurred before triggering any email notifications, for example. 

Some fields offer a constrained choice of values which the partner will need to map onto their own field values. For example, the studyLevel field might be Secondary/High School, Postgraduate, etc. 

Occasionally INTO may add new values, which will be unexpected by the partner’s integration. 

Ideally the integration will map the unexpected value to a safe known value (Other, for example) and/or warn an operator so the new value can be added and mapped to the partner system. 

However INTO’s Recruitment Partners also have API access to the INTO course catalog using the search API, the search catalog offers fast access to a wide variety of information regarding details such as start/end dates, durations, locations etc. The full field listing is available as a separate reference on this site.

The search functionality for INTO’s recruitment partners is fully elastic, it also adheres to the standards adopted by Microsoft to offer a fully searchable, facetable, and filterable set of data, the methods required for accessing the search API are in the ‘Search’ section on this site

Future developments of the Recruitment Partner API suite will allow INTO partners to be able to monitor the current status of their applications once they have been submitted. Any additions to the API suite will be announced as the APIs are published

INTO also offers our Recruitment Partners to ability to use the ‘Search and Apply Widget’, This prebuilt tool facilitates the use of INTO data to filter and search INTO data and to make an application 'Apply' to INTO all from one easily embedded tool. The widget also allows for the ability to ask questions about INTO with a chatbot.

Recruitment Partners should refer to the "Searching for courses" section of this document to be able to get information regarding INTO’s catalogue and detail course information

Existing Joint Venture Partners have the opportunity to use INTO’s Pathway API suite, this could be in addition to OR to replace their currently defined XML/XSD feeds that use more traditional interfacing technologies such as SMTP and file sharing. (For more information please see the XML section of this site)

This suite of APIs is designed to be easy to use and can provide Joint Venture Partners with the ability to create an interface between INTO’s student systems and their own in-house systems, allowing for student and course details to be created, updated and where appropriate transferred or cancelled from courses

This particular suite also contains the APIs necessary to search the INTO course catalogue (See the ‘Search’ section on this site) and send applications to INTO (See the ‘Creating a Lead with the Apply API’ section on this site)

All calls made via the suite, include two common parameters, namely version and token

Version control provides a structured approach to management of features as the API suite develops. 

Token is a Globally Unique Identifier (GUID) issued by the INTO API Administrator and based on the RFC 4122 standards.  INTO employ version 4 GUIDS for the Pathway API suite a typical example is as follows: FC1D4798-751E-4AAF-91A6-4AB1008F911F

The token is specific to the partner and represents the second level of security in the model employed for the API suite. The token is submitted as part of the call and ensures only data for that partner, is extracted or updated and not any other. 

Note: Based on the sensitive nature of the token, it is the Pathway Partners Interface Administrator’s responsibility for the issuance and secure handling of the token/GUID.

The following table comprises a summary of the calls available via the Pathway API suite.  Each call shows the direction of data flow along with its required parameters.

Call 1 uses the UTC - Coordinated Universal Time as its basis. 

The format of 'refreshdate' is: yyyy-mm-ddThh:mm:ss

Example payloads for REST GET and POST calls are available in the Pathways Reference Guide available on this site

INTO also has a set of APIs that are used for many other business functions and for 3^rd Party integration with bespoke and specialised systems, whilst the number and function of these APIs are not directly relevant to this developer site, if you feel that you require assistance with an integration using APIs that are not using the functions here please contact us