Academics
This group refers to top-level entities such as School, Programs, Subjects, and Academic Years. Programs are curriculum frameworks that ManageBac supports, and a Subject is a collection of delivered curricula. Academic Years define when the school is in session.
Submit a zip archive file for ManageBac to process as an import. The import mode is determined by the manifest.
The bundle is queued rather than processed inline: a 202 means ManageBac has taken responsibility for it and identifies the import that was created. Validation results and the outcome appear under Data Exchange history in ManageBac, where the run is listed as generated by API Caller.
The import is always created for the school owning the API credential.
Please note that source.systemCode defines a namespace that scopes sourcedId mappings from previous imports. These sourcedIds can be matched against on import. A bundle that declares no source.systemCode imports into the unnamed namespace, which it shares with every other bundle that declares none.
Only one OneRoster exchange runs per school at a time. While an import or export is already in flight this endpoint returns 409 instead of holding the bundle, so a caller can retry once the running exchange has finished. That response names the import in the way as import_id; when an export is what blocks the upload there is no import to name and the field is absent. An exchange that has not progressed for over an hour is treated as abandoned and stops blocking further uploads.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Accepted
Bad Request
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedConflict
Unprocessable Entity
POST /v2p2/one-roster/imports HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 17
{
"file": "binary"
}{
"error": "Access Denied"
}Create Academic Term
Creates an Academic Term within the specified Academic Year.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Program scope
diplomaAcademic Year ID
123Success
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedUnprocessable entity
POST /v2p2/school/programs/{program_code}/academic-years/{academic_year_id}/academic-terms HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 126
{
"academic_term": {
"name": "Term one.",
"starts_on": "2024-05-29",
"ends_on": "2024-07-29",
"locked": true,
"enable_exam_grade": false
}
}{
"error": "Access Denied"
}Delete Academic Term
Deletes an Academic Term from the specified Academic Year by ID.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Program scope
diplomaAcademic Year ID
123Academic Term ID
123Success
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedUnprocessable entity
DELETE /v2p2/school/programs/{program_code}/academic-years/{academic_year_id}/academic-terms/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"error": "Access Denied"
}Update Academic Term
Updates an Academic Term within the specified Academic Year by ID.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Program scope
diplomaAcademic Year ID
123Academic Term ID
123Success
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedNot Found
Unprocessable entity
PATCH /v2p2/school/programs/{program_code}/academic-years/{academic_year_id}/academic-terms/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 126
{
"academic_term": {
"name": "Term one.",
"starts_on": "2024-05-29",
"ends_on": "2024-07-29",
"locked": true,
"enable_exam_grade": false
}
}{
"error": "Access Denied"
}Retrieves an Academic Year by ID, including its associated Academic Terms.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Program code
diplomaUnique ID in ManageBac.
10010Success
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedNot Found
GET /v2p2/school/programs/{program_code}/academic-years/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"error": "Access Denied"
}Creates an Academic Year with its associated Academic Terms.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Program code
diplomaSuccess
Bad Request
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedPOST /v2p2/school/programs/{program_code}/academic-years HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 149
{
"academic_year": {
"terms_attributes": [
{
"name": "Term one.",
"starts_on": "2024-05-29",
"ends_on": "2024-07-29",
"locked": true,
"enable_exam_grade": false
}
]
}
}{
"error": "Access Denied"
}Retrieves the list of assessment types configured for a given program. Each assessment type includes its kind (e.g. summative, formative), display name, color code, and the assessment methods that are available or required for that type (binary, criteria, comment, points).
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
The short code identifying the program (e.g. "ibpyp", "diploma", "igcse").
ibpypSuccess
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedGET /v2p2/school/programs/{program_code}/assessment_types HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"error": "Access Denied"
}Get Academic Year Calendar
Retrieves the academic year calendar for a specific program and academic year. Returns the calendar configuration (type, rotation cycle length, days off, whether holidays are ignored) and an array of dates with their assigned rotation day numbers. Vacation days are excluded from the rotation sequence.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
The short code identifying the program (e.g. "diploma", "ibpyp").
diplomaThe unique numeric identifier of the academic year.
10010Success
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedNot Found
GET /v2p2/school/programs/{program_code}/academic-years/{academic_year_id}/calendar HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"error": "Access Denied"
}Retrieves a list of published term reports for the specified program. Each report includes download URLs for PDF, individual reports ZIP, and term grades ZIP when available. Only non-draft reports are returned.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Program code (e.g. diploma, myp, pyp, cp)
diplomaFilter by academic term ID
Filter by report type: final or interim:
finalinterim
Success
Unauthorized
No content
Program not found
GET /v2p2/school/programs/{program}/reports HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Retrieves a single published term report by ID, with download URLs for available files.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Program code
diplomaTerm report ID
Success
Unauthorized
No content
Not found
GET /v2p2/school/programs/{program}/reports/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Returns a 302 redirect to a pre-signed download URL for the requested file. Supported file types: pdf (master PDF), individual_reports (ZIP of individual student PDFs), term_grades (ZIP of term grades export).
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Program code (e.g. diploma, myp, pyp, cp)
diplomaTerm report ID
File type to download:
pdfindividual_reportsterm_grades
Redirect to download URL
Unauthorized
No content
Not found
GET /v2p2/school/programs/{program}/reports/{id}/download/{kind} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Retrieves a paginated list of Subject Groups for the specified program.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Program scope
ibpypAn integer defining which page to display.
An integer defining the number of records to display per page.
A timestamp to filter the modification date of results.
Success
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedGET /v2p2/school/programs/{program_code}/subject-groups HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"error": "Access Denied"
}Creates a new Subject Group for the specified program.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Program scope
hsSuccess
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedUnprocessable Entity
POST /v2p2/school/programs/{program_code}/subject-groups HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 53
{
"subject_group": {
"name": "Language",
"max_phase": "4"
}
}{
"error": "Access Denied"
}Retrieves a single Subject Group by ID.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Program scope
hsUnique ID for Subject Group in ManageBac.
10001Success
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedNot Found
GET /v2p2/school/programs/{program_code}/subject-groups/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"error": "Access Denied"
}Deletes a Subject Group by ID.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Program scope
hsSubject Group ID
10010Success
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedForbidden
Not Found
Unprocessable Entity
DELETE /v2p2/school/programs/{program_code}/subject-groups/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"error": "Access Denied"
}Updates an existing Subject Group by ID.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Program scope
hsSubject Group ID
10010Success
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedForbidden
Not Found
PATCH /v2p2/school/programs/{program_code}/subject-groups/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 53
{
"subject_group": {
"name": "Language",
"max_phase": "4"
}
}{
"error": "Access Denied"
}Retrieves a paginated list of Subjects for the specified program.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Program scope
ibpypAn integer defining which page to display.
An integer defining the number of records to display per page.
Success
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedGET /v2p2/school/programs/{program_code}/subjects HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"error": "Access Denied"
}Creates a new Subject for the specified program.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Program scope
hsSuccess
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedUnprocessable Entity
POST /v2p2/school/programs/{program_code}/subjects HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 302
{
"subject": {
"subject_group_id": 10001,
"name": "English",
"title": "English",
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
"scope_and_sequence_based_on": "phases",
"sl": false,
"hl": true,
"enabled": true,
"code": "X128"
}
}{
"error": "Access Denied"
}Retrieves a single Subject by ID.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Program scope
ibpypUnique ID for Subject in ManageBac.
10001Success
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedNot Found
GET /v2p2/school/programs/{program_code}/subjects/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"error": "Access Denied"
}Updates an existing Subject by ID.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Program scope
ibpypUnique ID for Subject in ManageBac.
10001Success
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedNot Found
Unprocessable Entity
PUT /v2p2/school/programs/{program_code}/subjects/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 302
{
"subject": {
"subject_group_id": 10001,
"name": "English",
"title": "English",
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
"scope_and_sequence_based_on": "phases",
"sl": false,
"hl": true,
"enabled": true,
"code": "X128"
}
}{
"error": "Access Denied"
}Deletes a Subject by ID.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Program scope
ibpypUnique ID for Subject in ManageBac.
10001Success
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedNot Found
DELETE /v2p2/school/programs/{program_code}/subjects/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"error": "Access Denied"
}Retrieves the School's basic information including name, country, language, logo URLs, and the list of enabled academic programs (e.g. IB Diploma, MYP, PYP).
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Success
Unauthorized
No content
GET /v2p2/school HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Retrieves academic years and their terms for each enabled program at the School. Results are grouped by program code (e.g. diploma, myp, ibpyp). Each academic year includes its terms with start/end dates and active status.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Filter by program code (e.g. 'diploma', 'myp', 'hs'). Omit to return all programs.
Filter by active status. When true, returns only currently active academic years.
Success
Unauthorized
No content
GET /v2p2/school/academic-years HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Retrieves the grade levels defined for each enabled program at the School. Grades are grouped by program and include the grade name, label, code, UID, and grade number. The label is the school's customized display name for the grade.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Success
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedGET /v2p2/school/grades HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"error": "Access Denied"
}Retrieves the subjects available for each enabled program at the School. Subjects are grouped by program code. Each subject includes its name, subject group, and level availability (HL/SL) where applicable. Deprecated subjects are excluded from the response.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Success
Unauthorized
No content
GET /v2p2/school/subjects HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Retrieves the term grade scales defined for each enabled program at the School. Each scale entry maps a percentage score threshold to a mark (e.g. score 95.0 maps to mark "7" for IB Diploma). These scales determine how numerical scores are converted to grade marks on term reports.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Success
Unauthorized
Returned when the API token is missing, invalid, or has been disabled.
Unauthorized to perform an action
Access DeniedGET /v2p2/school/term-grade-scales HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"error": "Access Denied"
}Retrieves the term grade rubrics configured for the School. Rubrics define the criteria or formulas used to calculate term grades. Each rubric includes its type (Criteria, Formula, or Custom Field), program code, and status. Criteria rubrics include their rubric options with values and descriptors. Formula rubrics specify the calculation method (AVG or SUM) and reference other rubric IDs.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Success
Unauthorized
No content
GET /v2p2/school/term-rubrics HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Last updated