Overview
This document describes how integration between Unitu and the University Student Record System works.
Features
Automated generic sync
Sync runs automatically every time new data snapshot sent by the University in asyncronous mode and usually takes few minutes to complete.
Sync is controlled by Unitu and can be enabled/disabled or set to dry-run mode by contacting Unitu Support Team / Customer Success Manager.
Student accounts provisioning
Student accounts are automatically provisioned for enrolled programmes and modules. For each record in the dataset, accounts are created automatically and enrolled to their programmes and modules if programme exists on Unitu by the Customer Success Manager.
Student account information updates
On every sync we check if students’ details are updated and reflect changes on Unitu. Currently, we automatically update the following fields: first name, last name, year, phone, personalEmail (first time only), id (first time only).
Disabling accounts for university leavers
On every sync we disable all accounts which are enabled on Unitu but not included in the latest data snapshot from the University. Account holders will be automatically logged out and won’t be able to login until their account is re-enabled.
Re-enabling accounts for university leavers
On every sync we re-enable accounts which are disabled on Unitu but appeared in the latest data snapshot from the university.
Enrolling/un-enrolling students to/from programmes
On every sync we automatically add and remove students to/from programmes and modules which are enrolled on Unitu. If a student programmes or modules changed in the latest data snapshot, we will remove them from the old programmes or modules and add them to the new ones automatically.
Syncing faculties/departments/programmes/modules
On every sync we automatically identify new entities which appear in the provided data snapshot and compare them to the latest known data on Unitu. There are no actions performed as a result, except highlighting it in a report which is available to Customer Success Managers to take further actions and discuss with the university about any university structure changes.
How to send data to our API
HTTP Post Request
- Prepare an HTTP POST request
- Header:
- API Key: <will be provided by us>
- Cache Control: ‘no-cache’
- Content Type: ‘application/json’
- Body
- Use the JSON object with the structure provided below
- Header:
- Send the above request to the url: “https://api.unitu.io/v1/sync”
Body Schema
Please provide the data in JSON format using the example below:
{
// List of faculties within the university (optional)
// Faculties can be omitted if the university structure does not include them
"faculties": [
{
"code": "FAC01", // Unique code for the faculty
"name": "Faculty of Science" // Name of the faculty
},
{
"code": "FAC02", // Unique code for the faculty
"name": "Faculty of Arts" // Name of the faculty
}
],
// List of departments within the university, optionally linked to faculties
"departments": [
{
"code": "DEP01", // Unique code for the department
"name": "Department of Computer Science", // Name of the department
"facultyCode": "FAC01" // (Optional) Code of the faculty this department belongs to
},
{
"code": "DEP02", // Unique code for the department
"name": "Department of History", // Name of the department
"facultyCode": "FAC02" // (Optional) Code of the faculty this department belongs to
}
],
// List of academic programmes managed by the university, linked to departments
"programmes": [
{
"code": "PROG01", // Unique code for the programme
"name": "Computer Science 101", // Name of the programme
"departmentCode": "DEP01" // Code of the department this programme belongs to
},
{
"code": "PROG02", // Unique code for the programme
"name": "European History", // Name of the programme
"departmentCode": "DEP02" // Code of the department this programme belongs to
}
],
// List of modules offered within programmes, detailing year-specific optional status
"modules": [
{
"code": "MOD01", // Unique code for the module
"name": "Introduction to Programming", // Name of the module
"programmeCode": "PROG01", // Code of the programme this module belongs to
"years": [ // Year-specific availability and optionality
{
"year": 1, // The year in which this module is offered
"isOptional": false // Indicates if the module is optional for this year
}
]
},
{
"code": "MOD02", // Unique code for the module
"name": "Data Structures", // Name of the module
"programmeCode": "PROG01", // Code of the programme this module belongs to
"years": [ // Year-specific availability and optionality
{
"year": 1, // The year in which this module is offered
"isOptional": true // Indicates if the module is optional for this year
}
]
},
{
"code": "MOD03", // Unique code for the module
"name": "Medieval Europe", // Name of the module
"programmeCode": "PROG02", // Code of the programme this module belongs to
"years": [ // Year-specific availability and optionality
{
"year": 1, // The year in which this module is offered
"isOptional": false // Indicates if the module is optional for this year
},
{
"year": 2, // The year in which this module is offered
"isOptional": true // Indicates if the module is optional for this year
}
]
}
],
// List of students enrolled in the university
"students": [
{
"id": "S123456", // (Optional) Unique identifier for the student. Can be userID from the student record system or 'cn' field from Active Directory
"firstName": "John", // First name of the student
"lastName": "Doe", // Last name of the student
"year": 1, // Academic year the student is currently enrolled in. Please note this field type is a nullable number with possible values (null, 0-7) and doesn't need quotes around it.
"email": "john.doe@university.edu", // University email address
"personalEmail": "john.doe@example.com", // (Optional) Personal email address
"phone": "+1234567890", // (Optional) Phone number
"programmeCodes": [ // Array of programme codes the student is enrolled in
"PROG01"
],
"moduleCodes": [ // (Optional) Array of module codes the student is enrolled in
"MOD01",
"MOD02"
],
"metadata": { // (Optional) Additional metadata for the student. Any string key-value pairs in camel-case format.
"campus": "Main Campus", // Campus where the student is attending
"preferredLanguage": "en" // Preferred language in ISO 639-1 format
}
}
],
// List of staff members working at the university
"staff": [
{
"id": "ST789012", // (Optional) Unique identifier for the staff member. Can be userID from the staff record system or 'cn' field from Active Directory
"firstName": "Jane", // First name of the staff member
"lastName": "Smith", // Last name of the staff member
"universityTitle": "Professor", // University title of the staff member
"email": "jane.smith@university.edu", // University email address
"personalEmail": "jane.smith@example.com", // (Optional) Personal email address
"phone": "+0987654321", // (Optional) Phone number
"facultyCodes": [ // Array of faculty codes the staff member is associated with
"FAC01"
],
"departmentCodes": [ // Array of department codes the staff member is associated with
"DEP01"
],
"programmeCodes": [ // Array of programme codes the staff member is associated with
"PROG01"
],
"moduleCodes": [ // (Optional) Array of module codes the staff member is associated with
"MOD01",
"MOD02"
],
"metadata": { // (Optional) Additional metadata for the staff member. Any string key-value pairs in camel-case format.
"campus": "City Campus", // Campus where the staff member is working
"preferredLanguage": "en" // Preferred language in ISO 639-1 format
}
}
]
}
An Example of a Post Request using curl:
curl -X POST \
https://api.unitu.io/v1/sync \
-H 'API_KEY: {your API KEY}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"faculties": [
{
"code": "FAC01",
"name": "Faculty of Science"
},
{
"code": "FAC02",
"name": "Faculty of Arts"
}
],
"departments": [
{
"code": "DEP01",
"name": "Department of Computer Science",
"facultyCode": "FAC01"
},
{
"code": "DEP02",
"name": "Department of History",
"facultyCode": "FAC02"
}
],
"programmes": [
{
"code": "PROG01",
"name": "Computer Science 101",
"departmentCode": "DEP01"
},
{
"code": "PROG02",
"name": "European History",
"departmentCode": "DEP02"
}
],
"modules": [
{
"code": "MOD01",
"name": "Introduction to Programming",
"programmeCode": "PROG01",
"years": [
{
"year": 1,
"isOptional": false
}
]
},
{
"code": "MOD02",
"name": "Data Structures",
"programmeCode": "PROG01",
"years": [
{
"year": 1,
"isOptional": true
}
]
},
{
"code": "MOD03",
"name": "Medieval Europe",
"programmeCode": "PROG02",
"years": [
{
"year": 1,
"isOptional": false
},
{
"year": 2,
"isOptional": true
}
]
}
],
"students": [
{
"id": "S123456",
"firstName": "John",
"lastName": "Doe",
"year": 1,
"email": "john.doe@university.edu",
"personalEmail": "john.doe@example.com",
"phone": "+1234567890",
"programmeCodes": [
"PROG01"
],
"moduleCodes": [
"MOD01",
"MOD02"
],
"metadata": {
"campus": "Main Campus",
"preferredLanguage": "en"
}
},
{
"id": "jodo22",
"firstName": "Joe",
"lastName": "Doe",
"year": 3,
"email": "joe.doe@university.edu",
"personalEmail": "joe.doe@example.com",
"phone": "+0987654321",
"programmeCodes": [
"PROG02"
],
"moduleCodes": [
"MOD03"
],
"metadata": {
"campus": "Main Campus",
"preferredLanguage": "en"
}
}
],
"staff": [
{
"id": "ST789012",
"firstName": "Jane",
"lastName": "Smith",
"universityTitle": "Professor",
"email": "jane.smith@university.edu",
"personalEmail": "jane.smith@example.com",
"phone": "+0987654321",
"facultyCodes": [
"FAC01"
],
"departmentCodes": [
"DEP01"
],
"programmeCodes": [
"PROG01"
],
"moduleCodes": [
"MOD01",
"MOD02"
],
"metadata": {
"campus": "City Campus",
"preferredLanguage": "en"
}
}
]
}'